FreeMat: vtkGraph

FreeMat

- Main Page
- Related Pages

vtkGraph

Section: Visualization Toolkit Filtering Classes

# Usage

vtkGraph is the abstract base class that provides all read-only API for graph data types. A graph consists of a collection of vertices and a collection of edges connecting pairs of vertices. The vtkDirectedGraph subclass represents a graph whose edges have inherent order from source vertex to target vertex, while vtkUndirectedGraph is a graph whose edges have no inherent ordering.

Graph vertices may be traversed in two ways. In the current implementation, all vertices are assigned consecutive ids starting at zero, so they may be traversed in a simple for loop from 0 to graph->GetNumberOfVertices() - 1. You may alternately create a vtkVertexListIterator and call graph->GetVertices(it). it->Next() will return the id of the next vertex, while it->HasNext() indicates whether there are more vertices in the graph. This is the preferred method, since in the future graphs may support filtering or subsetting where the vertex ids may not be contiguous.

Graph edges must be traversed through iterators. To traverse all edges in a graph, create an instance of vtkEdgeListIterator and call graph->GetEdges(it). it->Next() returns lightweight vtkEdgeType structures, which contain the public fields Id, Source and Target. Id is the identifier for the edge, which may be used to look up values in assiciated edge data arrays. Source and Target store the ids of the source and target vertices of the edge. Note that the edge list iterator DOES NOT necessarily iterate over edges in order of ascending id. To traverse edges from wrapper code (Python, Tcl, Java), use it->NextGraphEdge() instead of it->Next(). This will return a heavyweight, wrappable vtkGraphEdge object, which has the same fields as vtkEdgeType accessible through getter methods.

To traverse all edges outgoing from a vertex, create a vtkOutEdgeIterator and call graph->GetOutEdges(v, it). it->Next() returns a lightweight vtkOutEdgeType containing the fields Id and Target. The source of the edge is always the vertex that was passed as an argument to GetOutEdges(). Incoming edges may be similarly traversed with vtkInEdgeIterator, which returns vtkInEdgeType structures with Id and Source fields. Both vtkOutEdgeIterator and vtkInEdgeIterator also provide the wrapper functions NextGraphEdge() which return vtkGraphEdge objects.

An additional iterator, vtkAdjacentVertexIterator can traverse outgoing vertices directly, instead needing to parse through edges. Initialize the iterator by calling graph->GetAdjacentVertices(v, it).

vtkGraph has two instances of vtkDataSetAttributes for associated vertex and edge data. It also has a vtkPoints instance which may store x,y,z locations for each vertex. This is populated by filters such as vtkGraphLayout and vtkAssignCoordinates.

All graph types share the same implementation, so the structure of one may be shared among multiple graphs, even graphs of different types. Structures from vtkUndirectedGraph and vtkMutableUndirectedGraph may be shared directly. Structures from vtkDirectedGraph, vtkMutableDirectedGraph, and vtkTree may be shared directly with the exception that setting a structure to a tree requires that a "is a tree" test passes.

For graph types that are known to be compatible, calling ShallowCopy() or DeepCopy() will work as expected. When the outcome of a conversion is unknown (i.e. setting a graph to a tree), CheckedShallowCopy() and CheckedDeepCopy() exist which are identical to ShallowCopy() and DeepCopy(), except that instead of emitting an error for an incompatible structure, the function returns false. This allows you to programmatically check structure compatibility without causing error messages.

To construct a graph, use vtkMutableDirectedGraph or vtkMutableUndirectedGraph. You may then use CheckedShallowCopy to set the contents of a mutable graph type into one of the non-mutable types vtkDirectedGraph, vtkUndirectedGraph. To construct a tree, use vtkMutableDirectedGraph, with directed edges which point from the parent to the child, then use CheckedShallowCopy to set the structure to a vtkTree.

To create an instance of class vtkGraph, simply invoke its constructor as follows

      obj = vtkGraph

# Methods

The class vtkGraph has several methods that can be used. They are listed below. Note that the documentation is translated automatically from the VTK sources, and may not be completely intelligible. When in doubt, consult the VTK website. In the methods listed below, `obj` is an instance of the vtkGraph class.

- `string = obj.GetClassName ()`
- `int = obj.IsA (string name)`
- `vtkGraph = obj.NewInstance ()`
- `vtkGraph = obj.SafeDownCast (vtkObject o)`
- `vtkDataSetAttributes = obj.GetVertexData ()` - Get the vertex or edge data.
- `vtkDataSetAttributes = obj.GetEdgeData ()` - Get the vertex or edge data.
- `int = obj.GetDataObjectType ()` - Initialize to an empty graph.
- `obj.Initialize ()` - Initialize to an empty graph.
- `obj.GetPoint (vtkIdType ptId, double x[3])` - These methods return the point (0,0,0) until the points structure is created, when it returns the actual point position. In a distributed graph, only the points for local vertices can be retrieved.
- `vtkPoints = obj.GetPoints ()` - Returns the points array for this graph. If points is not yet constructed, generates and returns a new points array filled with (0,0,0) coordinates. In a distributed graph, only the points for local vertices can be retrieved or modified.
- `obj.SetPoints (vtkPoints points)` - Returns the points array for this graph. If points is not yet constructed, generates and returns a new points array filled with (0,0,0) coordinates. In a distributed graph, only the points for local vertices can be retrieved or modified.
- `obj.ComputeBounds ()` - Compute the bounds of the graph. In a distributed graph, this computes the bounds around the local part of the graph.
- `obj.GetBounds (double bounds[6])` - Return a pointer to the geometry bounding box in the form (xmin,xmax, ymin,ymax, zmin,zmax). In a distributed graph, this computes the bounds around the local part of the graph.
- `long = obj.GetMTime ()` - The modified time of the graph.
- `obj.GetOutEdges (vtkIdType v, vtkOutEdgeIterator it)` - Initializes the out edge iterator to iterate over all outgoing edges of vertex v. For an undirected graph, returns all incident edges. In a distributed graph, the vertex v must be local to this processor.
- `vtkIdType = obj.GetDegree (vtkIdType v)` - The total of all incoming and outgoing vertices for vertex v. For undirected graphs, this is simply the number of edges incident to v. In a distributed graph, the vertex v must be local to this processor.
- `vtkIdType = obj.GetOutDegree (vtkIdType v)` - The number of outgoing edges from vertex v. For undirected graphs, returns the same as GetDegree(). In a distributed graph, the vertex v must be local to this processor.
- `obj.GetOutEdge (vtkIdType v, vtkIdType index, vtkGraphEdge e)` - Random-access method for retrieving outgoing edges from vertex v. The method fills the vtkGraphEdge instance with the id, source, and target of the edge. This method is provided for wrappers, GetOutEdge(vtkIdType, vtkIdType) is preferred.
- `obj.GetInEdges (vtkIdType v, vtkInEdgeIterator it)` - Initializes the in edge iterator to iterate over all incoming edges to vertex v. For an undirected graph, returns all incident edges. In a distributed graph, the vertex v must be local to this processor.
- `vtkIdType = obj.GetInDegree (vtkIdType v)` - The number of incoming edges to vertex v. For undirected graphs, returns the same as GetDegree(). In a distributed graph, the vertex v must be local to this processor.
- `obj.GetInEdge (vtkIdType v, vtkIdType index, vtkGraphEdge e)` - Random-access method for retrieving incoming edges to vertex v. The method fills the vtkGraphEdge instance with the id, source, and target of the edge. This method is provided for wrappers, GetInEdge(vtkIdType, vtkIdType) is preferred.
- `obj.GetAdjacentVertices (vtkIdType v, vtkAdjacentVertexIterator it)` - Initializes the adjacent vertex iterator to iterate over all outgoing vertices from vertex v. For an undirected graph, returns all adjacent vertices. In a distributed graph, the vertex v must be local to this processor.
- `obj.GetEdges (vtkEdgeListIterator it)` - Initializes the edge list iterator to iterate over all edges in the graph. Edges may not be traversed in order of increasing edge id. In a distributed graph, this returns edges that are stored locally.
- `vtkIdType = obj.GetNumberOfEdges ()` - The number of edges in the graph. In a distributed graph, this returns the number of edges stored locally.
- `obj.GetVertices (vtkVertexListIterator it)` - Initializes the vertex list iterator to iterate over all vertices in the graph. In a distributed graph, the iterator traverses all local vertices.
- `vtkIdType = obj.GetNumberOfVertices ()` - The number of vertices in the graph. In a distributed graph, returns the number of local vertices in the graph.
- `obj.SetDistributedGraphHelper (vtkDistributedGraphHelper helper)` - Sets the distributed graph helper of this graph, turning it into a distributed graph. This operation can only be executed on an empty graph.
- `vtkDistributedGraphHelper = obj.GetDistributedGraphHelper ()` - Retrieves the distributed graph helper for this graph
- `obj.ShallowCopy (vtkDataObject obj)` - Shallow copies the data object into this graph. If it is an incompatible graph, reports an error.
- `obj.DeepCopy (vtkDataObject obj)` - Deep copies the data object into this graph. If it is an incompatible graph, reports an error.
- `obj.CopyStructure (vtkGraph g)` - Does a shallow copy of the topological information, but not the associated attributes.
- `bool = obj.CheckedShallowCopy (vtkGraph g)` - Performs the same operation as ShallowCopy(), but instead of reporting an error for an incompatible graph, returns false.
- `bool = obj.CheckedDeepCopy (vtkGraph g)` - Performs the same operation as DeepCopy(), but instead of reporting an error for an incompatible graph, returns false.
- `obj.Squeeze ()`
- `obj.ReorderOutVertices (vtkIdType v, vtkIdTypeArray vertices)` - Reorder the outgoing vertices of a vertex. The vertex list must have the same elements as the current out edge list, just in a different order. This method does not change the topology of the graph. In a distributed graph, the vertex v must be local.
- `bool = obj.IsSameStructure (vtkGraph other)` - Returns true if both graphs point to the same adjacency structure. Can be used to test the copy-on-write feature of the graph.
- `vtkIdType = obj.GetSourceVertex (vtkIdType e)` - Retrieve the source and target vertices for an edge id. NOTE: The first time this is called, the graph will build a mapping array from edge id to source/target that is the same size as the number of edges in the graph. If you have access to a vtkOutEdgeType, vtkInEdgeType, vtkEdgeType, or vtkGraphEdge, you should directly use these structures to look up the source or target instead of this method.
- `vtkIdType = obj.GetTargetVertex (vtkIdType e)` - Retrieve the source and target vertices for an edge id. NOTE: The first time this is called, the graph will build a mapping array from edge id to source/target that is the same size as the number of edges in the graph. If you have access to a vtkOutEdgeType, vtkInEdgeType, vtkEdgeType, or vtkGraphEdge, you should directly use these structures to look up the source or target instead of this method.
- `vtkIdType = obj.GetNumberOfEdgePoints (vtkIdType e)` - Get the number of edge points associated with an edge.
- `double = obj.GetEdgePoint (vtkIdType e, vtkIdType i)` - Get the x,y,z location of a point along edge e.
- `obj.ClearEdgePoints (vtkIdType e)` - Clear all points associated with an edge.
- `obj.SetEdgePoint (vtkIdType e, vtkIdType i, double x[3])` - Set an x,y,z location of a point along an edge. This assumes there is already a point at location i, and simply overwrites it.
- `obj.SetEdgePoint (vtkIdType e, vtkIdType i, double x, double y, double z)` - Adds a point to the end of the list of edge points for a certain edge.
- `obj.AddEdgePoint (vtkIdType e, double x[3])` - Adds a point to the end of the list of edge points for a certain edge.
- `obj.AddEdgePoint (vtkIdType e, double x, double y, double z)` - Copy the internal edge point data from another graph into this graph. Both graphs must have the same number of edges.
- `obj.ShallowCopyEdgePoints (vtkGraph g)` - Copy the internal edge point data from another graph into this graph. Both graphs must have the same number of edges.
- `obj.DeepCopyEdgePoints (vtkGraph g)` - Copy the internal edge point data from another graph into this graph. Both graphs must have the same number of edges.
- `vtkGraphInternals = obj.GetGraphInternals (bool modifying)` - Returns the internal representation of the graph. If modifying is true, then the returned vtkGraphInternals object will be unique to this vtkGraph object.
- `obj.GetInducedEdges (vtkIdTypeArray verts, vtkIdTypeArray edges)` - Fills a list of edge indices with the edges contained in the induced subgraph formed by the vertices in the vertex list.
- `vtkFieldData = obj.GetAttributesAsFieldData (int type)` - Returns the attributes of the data object as a vtkFieldData. This returns non-null values in all the same cases as GetAttributes, in addition to the case of FIELD, which will return the field data for any vtkDataObject subclass.
- `vtkIdType = obj.GetNumberOfElements (int type)` - Get the number of elements for a specific attribute type (VERTEX, EDGE, etc.).
- `obj.Dump ()` - Dump the contents of the graph to standard output.