Topology Detail

Creating and Managing Topologies

AcMapTopologyAcMapTopologyManager

• Close a topology - Close()
• Create an instance of topology - AcMapTopology()
• Create a fully specified topology - Create() (twoforms). See also ETopologyType enum and ECreateOptions enum.

  Prior to creating a new topology with Create(), call the following functions to override the default centroid-, edge-, and node-creation settings:

• SetCentroidCreationSettings(). See also AcMapPointCreationSettings class.
• SetEdgeCreationSettings(). See also AcMapEntityCreationSettings class.
• SetNodeCreationSettings(). See also AcMapPointCreationSettings class.

• Delete a topology - Delete()
• Existence test - TopologyExists() (twoforms). See also ETopologyScope enum.
• Open a topology in the current drawing - Open(). See also EOpenMode enum.
• Open a topology in the current and source drawings - Open(). See also EOpenMode enum and EAuditResults enum.
• Update a topology - Refresh()/NeedsRefresh()

For topology source-code samples, see Topology Samples.

// Create a topology object, verify it, close it, and destroy it.
AcMap::EErrCode errCode;
ETopologyType eType = ePoint;
const char* pszTopologyName = "MyNodeTopology";
// For safety, usually add the existence test
// if (AcMapTopologyManager::TopologyExists(pszTopologyName)){...}
// before creating a new topology.
AcMapTopology* pTopology = new AcMapTopology(pszTopologyName);
// See <a href="#samples">Topology Samples</a> for sample code
// that shows how to populate these arrays.
AcDbObjectIdArray edgeObjIds;
AcDbObjectIdArray nodeObjIds;
AcDbObjectIdArray centroidObjIds;
...
errCode = pTopology->Create(edgeObjIds, nodeObjIds, centroidObjIds, int(eType));
if(AcMap::kOk == errCode)
{
// Verify the result by closing and reopening the newly created topology.
pTopology->Close();
pTopology->Open(AcMapTopology::eForRead);
// Another test: Confirm that the topology has the correct nodes.
AcMapNodePtrArray apNodes;
if (AcMap::kOk == pTopology->GetNodes(apNodes))
{
// Verify the nodes....
apNodes.Empty();
}
else
{
// Cannot get nodes - handle the error.
}
}
else
{
// Cannot create topology - handle the error.
}
// Clean up.
pTopology->Close();
delete pTopology;
pTopology = NULL;

Managing Topology Properties

AcMapTopologyAcMapTopologyManagerAcMapTopologySource

• Completeness - IsComplete()
• Description - GetDescription()/SetDescription()
• Error-marker styles - GetMarkerStyles(). See also AcMapMarkerStyles class.
• Highlighting - ShowGeometry()
• Loaded or unloaded - IsLoaded()
• Name - GetName()/Rename()
• Scope - GetTopologyScope(). See also ETopologyScope enum.
• Source - GetTopologySource()/GetSource()
• Status - GetStatus(). See also EStatus enum.
• Type - GetType()/IsFixedType()/IsLinearType()/IsLogicalType()/IsPointType()/IsPolygonType(). See also ETopologyType enum.

Note GetTopologySource() takes topology source information as AcMapTopologySource instances in the array typedef AcArray< AcMapTopologySource > AcMapTopologySourceArray.

For topology source-code samples, see Topology Samples.

// Rename a topology.
AcMap::EErrCode errCode;
const char* pszTopologyName = "MyTopology";
const char* pszNewTopologyName = "MyRenamedTopology";
errCode = AcMapTopologyManager::Rename(pszTopologyName, pszNewTopologyName);
if (AcMap::kOk == errCode)
{
// Process the renamed topology.
// Perhaps inspect and change its description.
...
}
else if (AcMap::kErrTopInvalidName == errCode)
{
// Handle the bad topology name. A bad name typically is 
// NULL, empty, too long, or has nonalphabetic characters.
}
else if (AcMap::kErrTopNotExist == errCode)
{
// The given topology doesn't exist.
}
else 
{
// Handle a different type of error.
}

Adding, Editing, and Deleting Topology Elements

AcMapTopologyAcMapTopoFullEdgeAcMapTopoNodeAcMapTopoPolygon

• Add a curve (linear object) - AddCurveObject()
• Add a point - AddPointObject()
• Add polygon edges - AddPolygons()
• Delete a node - DeleteNode() (twoforms)
• Delete a polygon - DeletePolygon() (twoforms)
• Delete an edge - DeleteEdge()
• Merge many neighboring polygons - MergePolygons() (twoforms)
• Merge two neighboring polygons - MergePolygons() (twoforms)
• Move a node - MoveNode() (twoforms)
• Split a polygon - SplitPolygon() (twoforms)

For topology source-code samples, see Topology Samples.

// Move a node in a topology.
AcMap::EErrCode errCode;
const char* pszTopologyName = "MyNodeTopology";
AcMapTopology* pTopology = new AcMapTopology(pszTopologyName);
// Open the topology for write.
if (AcMap::kOk == pTopology->Open(AcMapTopology::eForWrite))
{
// Get the node of interest (with object ID = 4, in this case)
// and move it to a new location.
AcMapTopoNode* pNode = NULL;
pTopology->GetNode(pNode, 4);
AcGePoint3d newLocation(39.0, 15.0, 0.0000);
if (AcMap::kOk != pTopology->MoveNode(*pNode, newLocation))
{
// Handle the error.
} 
delete pNode;
pTopology->Close();
}
else
{
// Cannot open topology - handle the error.
}

Querying Topologies

AcMapTopologyAcMapTopoFullEdgeAcMapTopoNodeAcMapTopoPolygon

• Specific edge - FindEdge()
• Edge nearest a point - FindEdge()
• Edge, node, or polygon nearest a point - FindTopologyObject(). See also AcMapTopoElement class.
• Node nearest a point - FindNode()
• Polygon containing a point - FindPolygon()
• Polygons neighboring a curve - FindNeighborPolygons(). See also Arrays of Topology Elements.

For topology source-code samples, see Topology Samples.

// Find a polygon in a topology.
AcMap::EErrCode errCode;
const char* pszTopologyName = "MyPolygonTopology";
AcMapTopology* pTopology= new AcMapTopology(pszTopologyName);
// Open the topology from the source drawing for read.
if (AcMap::kOk == pTopology->Open(AcMapTopology::eForRead, true, false, NULL))
{
// Find the polygon containing a specific point.
AcMapTopoPolygon* pPolygon;
AcGePoint3d point(30.0, 12.0, 0.0000);
errCode = pTopology->FindPolygon(pPolygon, point);
if (AcMap::kOk == errCode)
{
// Is this a polygon of interest (with object ID = 184, in this case)?
if (pPolygon->GetID() == 184)
{
// Process the polygon.
}
}
else
{
// FindPolygon() failed - handle the error.
}
// Clean up.
delete pPolygon;
pPolygon = NULL;
pTopology->Close();
}
else
{
// Failed to open topology - handle the error.
}

Retrieving Topology Elements

AcMapTopologyAcMapTopoFullEdgeAcMapTopoHalfEdgeAcMapTopoNodeAcMapTopoPolygon

• All AutoCAD entities - GetEntityIds()
• All full edges - GetFullEdges(). See also Arrays of Topology Elements.
• All nodes - GetNodes(). See also Arrays of Topology Elements.
• All polygons - GetPolygons(). See also Arrays of Topology Elements.
• Specific AutoCAD entity - GetEntityId()
• Specific full edge - GetFullEdge()
• Specific half edge - GetBackwardEdge()/GetForwardEdge()
• Specific node - GetNode()
• Specific polygon - GetPolygon()

For topology source-code samples, see Topology Samples.

// Get the nodes of a topology.
AcMap::EErrCode errCode;
const char* pszTopologyName = "MyNodeTopology";
AcMapTopology* pTopology = new AcMapTopology(pszTopologyName);
AcMapNodePtrArray apNodes;
// Open the topology for read.
if (AcMap::kOk != pTopology->Open(AcMapTopology::eForRead, true, false, NULL))
{
// Failed to open topology - handle the error.
}
if (Acad::eOk == pTopology->GetNodes(apNodes))
{
// Process each node.
for (int i = 0; i < apNodes.length(); i++)
{
// Get the node location.
AcGePoint3d point;
errCode = apNodes[i]->GetLocation(point);
if(Acad::eOk == errCode)
{
// Process the node.
}
}
}
else
{
// GetNodes() failed - handle the error.
}
// Clean up.
apNodes.Empty();
pTopology->Close();

Managing Topology Elements

AcMapTopology

• Full edges - AcMapTopoFullEdge instances (derived from AcMapTopoElement)

• Associated AutoCAD entity - GetEntity()
• Associated polygon - GetPolygon(). See also AcMapTopoPolygon class.
• Associated ring - GetRing(). See also AcMapTopoRing class.
• Associated topology - GetTopology(). See also AcMapTopology class.
• Coincident or nearby point - IsOnThisObject()
• Edge direction - GetDirection()/SetDirection(). See also EDirection enum.
• Edge length - GetLength()
• Edge resistance - GetResistance()/SetResistance()
• Next edge - GetNextEdge()
• Next node - GetNextNode()
• Traversing half edge - GetHalfEdge()
• Unique identifier - GetID()

• Half edges - AcMapTopoHalfEdge instances

• Associated polygon - GetPolygon(). See also AcMapTopoPolygon class.
• Associated ring - GetRing(). See also AcMapTopoRing class.
• Associated topology - GetTopology(). See also AcMapTopology class.
• Containing full edge - GetFullEdge()
• Edge resistance - GetResistance()/SetResistance()
• Next edge - GetNextEdge()
• Next/previous node - GetNextNode()/GetPreviousNode()

• Nodes - AcMapTopoNode instances (derived from AcMapTopoElement)

• Associated AutoCAD entity - GetEntity()
• Associated topology - GetTopology(). See also AcMapTopology class.
• Coincident or nearby point - IsOnThisObject()
• Edges - GetEdges(). See also AcMapTopoHalfEdge class and Arrays of Topology Elements.
• Next edge - GetNextEdge() (twoforms). See also AcMapTopoFullEdge and AcMapTopoHalfEdge classes.
• Node location - GetLocation()/SetLocation()
• Node mobility - IsMoveable()/SetIsMoveable()
• Node resistance - GetResistance()/SetResistance()
• Unique identifier - GetID()

• Polygons - AcMapTopoPolygon instances (derived from AcMapTopoElement)

• Associated AutoCAD entity - GetEntity()
• Associated topology - GetTopology(). See also AcMapTopology class.
• Coincident or nearby point - IsOnThisObject()
• Hierarchical parent/children polygons - GetHierParent()/GetHierChildren()
• Multi-polygon parent - GetParent()
• Polygon area - GetArea()
• Polygon boundary - GetBoundary(). See also Arrays of Topology Elements.
• Polygon centroid - GetCentroid()
• Polygon perimeter - GetPerimeter()
• Traversal to neighboring polygon - Traverse()
• Unique identifier - GetID()

• Rings - AcMapTopoRing instances

• Constituent edges - GetEdges(). See also AcMapTopoHalfEdge class and Arrays of Topology Elements.
• First edge - GetStartEdge(). See also AcMapTopoHalfEdge class.
• Outer polygon boundary - IsExterior(). See also AcMapTopoPolygon::GetBoundary().
• Ring area - GetArea()
• Ring length - GetLength()

For topology source-code samples, see Topology Samples.

// Get a specific polygon from a topology and print 
// statistics for its rings.
AcMap::EErrCode errCode;
char* pszTopologyName = "MyTopology";
AcMapTopology* pMapTopology = NULL;
// Open the topology for read.
if (AcMapTopologyManager::TopologyExists(pszTopologyName))
{
pMapTopology = new AcMapTopology(pszTopologyName);
if(AcMap::kOk != pMapTopology->Open(AcMapTopology::eForRead))
{
// Cannot open topology - handle the error.
}
}
// Get a polygon of interest (with object ID = 10, in this case)
// and retrieve its rings with GetBoundary().
AcMapTopoPolygon* pPolygon = NULL;
if (AcMap::kOk == pTopology->GetPolygon(pPolygon, 10))
{
// Get the polygon's rings.
AcMapRingPtrArray apRings;
errCode = pPolygon->GetBoundary(apRings);
if (AcMap::kOk == errCode)
{
// Get statistics for each ring.
int nRings = apRings.length(); // Number of rings.
for (int nRingIndex = 0; nRingIndex < nRings; nRingIndex++)
{
AcMapTopoRing* pRing = apRings[nRingIndex];
// Is ring exterior or interior?.
char* pszExtOrInt = pRing->IsExterior() ? "exterior" : "interior";
// Print the rings' area and length.
acutPrintf("\n#%d is %10s, Area: %-0.4lf Length: %-0.4lf",
(nRingIndex + 1), pszExtOrInt, pRing->GetArea(), pRing->GetLength());
}
apRings.Empty(); // Free the array of rings.
}
else
{
// Cannot get the polygon's boundary - handle the error.
}
}
else
{
// Cannot get the specified polygon - handle the error.
}
// Clean up.
delete pPolygon;
pPolygon = NULL;
pMapTopology->Close();

<a id="analyzing">Analyzing Topologies

• Shortest-path trace - A shortest-path trace uses a network topology to calculate the shortest path between two points or determine the optimal route based on values of direction and resistance. In a street network, for example, you can find the shortest path between a fire station and a school. Use TraceLeastCostPath() to calculate a shortest-path trace and an AcMapTraceParameters instance to set trace parameters.
• Best-route trace - A best-route trace uses a network topology to calculate the best route from a starting point to an end point, with one or more intermediate points. AutoCAD Map 3D determines the optimal route based on values of direction and resistance. In a street network, for example, you can find the best route to travel when visiting several customer sites from a hotel. Use TraceBestPath() to calculate a best-route trace and an AcMapTraceParameters instance to set trace parameters.
• Flood trace - A network flood trace traces out from a point in all directions, given the point where the network starts and the maximum distance that the network can traverse. A flood trace determines how many links and nodes can be traveled before the accumulated resistance exceeds the specified maximum resistance. You can find all restaurants within a 10-minute walk of a hotel, for example, or check the integrity of a network topology (if some links are not flooded, the topology is incomplete). Use TraceFlood() to calculate a flood trace and an AcMapFloodParameters instance to set trace parameters.
• Buffering a topology - Buffer analysis, or buffering, identifies objects within a specified offset of elements in node, network, and polygon topologies. A buffer is a zone that is drawn around a topology. You can specify a buffer on either side of a river to show the extent of a flood plain, for example. Use Buffer() to create a new topology with a buffer setting.
• Dissolving a composite topology - If a topology contains many smaller polygons, you can create a new topology by combining polygons that share the same data value in a specified field, called the dissolve field, which can be an object-data field or a column in a linked external database. Use Dissolve() to dissolve a topology.
• Overlaying topologies - Overlay analysis lets you overlay topologies that are loaded into the current drawing. The three types of overlay analysis are nodes with polygons, networks with polygons, and polygons with polygons. When you overlay two topologies, you choose the method in which the two selected topologies interact. In some cases, the result varies according to which topology is the source and which is the overlay. You have the following overlay options:
• Clip() - A clip operation uses the overlay polygon topology as a boundary. The parts of the source polygons outside the overlay polygons are clipped and discarded. You can use this option to show polygons within a boundary polygon, such as a city or state boundary.
• Erase() - An erase operation uses the overlay polygon topology like a mask and erases everything in the source polygon topology that is covered by the overlay topology.
• Identity() - An identity operation works like Union() on the source topology and like Intersect() on the overlay topology. Use Identity() to combine nodes, links, or polygons with polygons and keep all the input geometry. Identity() creates one topology with one link where the link is crossed by the overlay topology.
• Intersect() - An intersect operation combines topologies and keeps only the common geometry. Intersect() acts like the Boolean AND operation. The results are the same whichever topology is chosen as the first or second. Object data is combined for the two operations.
• Paste() - A paste operation pastes the overlay polygon topology on top of the source polygons. The source polygons not covered by the overlay remain. Paste() can be used with only polygons.
• Union() - A union operation combines polygons with polygons and keeps all geometry. Union() acts like the Boolean OR operation and can be used with only polygons. You can combine parcels with soils information for property assessment, for example. Use Union() to maintain both sets of geometry together and pull them apart as needed.
• The overlay functions all take source and overlay data as AcMapTopoOverlayData instances in the array typedef AcArray< AcMapTopoOverlayData > AcMapOverlayDataArray.

Note Before creating new topologies by buffering or overlaying existing topologies, you can call SetCentroidCreationSettings(), SetEdgeCreationSettings(), and SetNodeCreationSettings() to override the default topology-creation values.

For topology source-code samples, see Topology Samples.

// Two topologies are needed: source and overlay.
const char* pszSourceTopologyName = "MyNodeTopology";
AcMapTopology* pSourceTopology = new AcMapTopology(pszSourceTopologyName);
const char* pszOverlayTopologyName = "MyPolygonTopology";
AcMapTopology* pOverlayTopology = new AcMapTopology(pszOverlayTopologyName);
AcMap::EErrCode errCode;
// Open both source and overlay topologies for read.
if(AcMap::kOk == pSourceTopology->Open(AcMapTopology::eForRead))
{
if(AcMap::kOk == pOverlayTopology->Open(AcMapTopology::eForRead))
{
// Create the intersection of the source and overlay topologies.
errCode = pSourceTopology->Intersect(pOverlayTopology, "OutputTopo", "Intersect", NULL, NULL, NULL);
if(AcMap::kOk == errCode)
{
// Process the topology intersection.
}
else
{ 
// Cannot create topology intersection - handle the error.
}
pOverlayTopology->Close();
}
else
{
// Cannot open overlay topology - handle the error.
}
pSourceTopology->Close();
}
else
{
// Cannot open source topology - handle the error.
}

Using Iterators

AcMapTopoIteratorAcMapTopology

• Count the number of topologies - Count()
• Last-element flag - IsDone()
• Move to first/next element - First()/Next()
• Current topology - GetTopology()
• Current topology's name - GetName()
• Current topology's description - GetDescription()
• Current topology's type - GetType()

For topology source-code samples, see Topology Samples.

AcMap::EErrCode errCode;
// Initialize the iterator.
AcMapTopoIterator* pIterator = new AcMapTopoIterator;
AcMapTopology* pTopology = NULL;
// Iterate through the topology objects.
pIterator->First();
while (!pIterator->IsDone())
{
pIterator->GetTopology(pTopology);
// Process the topology...
errCode = pIterator->Next();
}
delete pIterator;
delete pTopology;
// To iterate with a for-loop: 
// for (pIterator.First(); !pIterator.IsDone(); pIterator.Next()) {...}

Arrays of Topology Elements

AcMapTopoElementPtrArray

For topology source-code samples, see Topology Samples.

Handling Errors

Many functions in the various topology classes return an AcMap::EErrCode error code. When a particular function returns an error code, read that function's documentation for function-specific error conditions rather than relying on only the generic error descriptions in the AcMap::EErrCode documentation.

Other Information Sources

• For more information about topology in AutoCAD Map 3D, choose Help > AutoCAD Map 3D Help > Contents tab (or press F1), and then navigate to Using AutoCAD Map 3D (by feature) > Topology (Spatial Analysis).
• For a topology tutorial in AutoCAD Map 3D, choose Help > Tutorials > Contents tab, and then choose "Using Topology and Spatial Analysis".
• For information about object data in AutoCAD Map 3D, choose Help > AutoCAD Map 3D Help > Contents tab (or press F1), and then navigate to Using AutoCAD Map 3D (by feature) > Object Data.

Topology Samples

To view code samples of topology functions, open the Samples folder in your AutoCAD Map 3D ObjectARX installation and navigate to Map Samples\Topology.

Topology Classes, Namespaces, and Globals

To view the topology classes, namespaces, and globals, click the following links:

AcMapTopology Class

AcMapTopoElement Class

AcMapTopoFullEdge Class

AcMapTopoHalfEdge Class

AcMapTopoNode Class

AcMapTopoPolygon Class

AcMapTopoRing Class

AcMapTopoIterator

AcMapTopologySource Class

AcMapTopoOverlayData Class

AcMapEntityCreationSettings Class

AcMapPointCreationSettings Class

AcMapFloodParameters Class

AcMapTraceParameters Class

AcMapNetAnalysisParameters Class

AcMapMarkerStyles Class

AcMapTopoElementPtrArray Template Class

AcMapObjectPtrArray Class

AcMapFullEdgePtrArray Class

AcMapHalfEdgePtrArray Class

AcMapNodePtrArray Class

AcMapPolygonPtrArray Class

AcMapRingPtrArray Class

AcMapTopologyManager Namespace

AcMapObjectDataField Global Struct

AcMapObjectDataTable Global Struct

ETopologyMarkType Global Enum

ETopologyType Global Enum