Topology
Topology
Centroids
Topology Detail
A node topology defines the interrelation of nodes (point objects). Node topologies often are used in conjunction with other topologies in analysis. Examples of node topologies include street lights, city-maintained trees, or drill holes for core samples. A network topology considers the interconnection of links (lines) forming a linear network. Links can connect nodes. Examples of network topologies include a street network and a water-distribution application that traces the flow of water from a pumping station to residences. A polygon topology defines polygons that represent enclosed areas such as land parcels and census tracts. A single link defines the common boundary between adjacent areas. A polygon topology can be used for tax assessment and land planning in which parcels of land are represented by polygons. Polygon topologies can represent political boundaries, such as voting districts, city, state, or provincial boundaries, special districts, and school districts.
With topologies, you can perform spatial analyses such as:
- Trace through network topologies (shortest-path traces, best-route analysis, and flood traces)
- Find the area within a certain distance of map features (by creating buffers)
- Dissolve and overlay polygon topologies
- Determine conditions of adjacency (what is next to what), containment (what is enclosed by what), and proximity (how close something is to something else)
Topology information is stored as object data on each element that makes up the topology. This data can be saved as part of the current map, or saved back to a source drawing. Because topology is definable for a map, identifiers used to store the topology are unique to the map. Topology in each drawing must be separate and unique. Autodesk Map does not support topology data that spans several drawing files (such as tiled maps) unless they are combined in a project.
You must create centroids for mpolygons and closed polylines before building a topology with them.
See
Creating and Managing Topologies
AcMapTopology AcMapTopologyManager
- Close a topology - Close()
- Create an instance of topology - AcMapTopology()
- Create a fully specified
topology - Create() (two forms).
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() (two forms). 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
// 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;
AcMapTopology AcMapTopologyManager AcMapTopologySource
- 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
// 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
AcMapTopology AcMapTopoFullEdge AcMapTopoNode AcMapTopoPolygon
- Add a curve (linear object) - AddCurveObject()
- Add a point - AddPointObject()
- Add polygon edges - AddPolygons()
- Delete a node - DeleteNode() (two forms)
- Delete a polygon - DeletePolygon() (two forms)
- Delete an edge - DeleteEdge()
- Merge many neighboring polygons - MergePolygons() (two forms)
- Merge two neighboring polygons - MergePolygons() (two forms)
- Move a node - MoveNode() (two forms)
- Split a polygon - SplitPolygon() (two forms)
For
topology source-code samples, see
// 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.
}
AcMapTopology AcMapTopoFullEdge AcMapTopoNode AcMapTopoPolygon
- 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.
}
AcMapTopology AcMapTopoFullEdge AcMapTopoHalfEdge AcMapTopoNode AcMapTopoPolygon
- 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
// 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();
- 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() (two forms). 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
// 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
// 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.
}
AcMapTopoIterator AcMapTopology
- 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
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()) {...}
| Array class | Holds pointers to |
|---|---|
| AcMapFullEdgePtrArray | AcMapTopoFullEdge instances |
| AcMapHalfEdgePtrArray | AcMapTopoHalfEdge instances |
| AcMapNodePtrArray | AcMapTopoNode instances |
| AcMapObjectPtrArray | AcMapTopoElement instances |
| AcMapPolygonPtrArray | AcMapTopoPolygon instances |
| AcMapRingPtrArray | AcMapTopoRing instances |
For
topology source-code samples, see
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.
- 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.
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:
AcMapEntityCreationSettings Class
AcMapPointCreationSettings Class
AcMapNetAnalysisParameters Class
AcMapTopoElementPtrArray Template Class
AcMapTopologyManager Namespace
AcMapObjectDataField Global Struct