Fix extremely confusing network graph API naming

Since names of api calls were backwards to expectations
qgis · Oct 31, 2017 · ab05fe7 · ab05fe7
1 parent b337335
commit ab05fe7
Show file tree

Hide file tree

Showing 13 changed files with 130 additions and 115 deletions.
diff --git a/python/analysis/network/qgsgraph.sip b/python/analysis/network/qgsgraph.sip
@@ -41,15 +41,17 @@ class QgsGraphEdge
  :rtype: list of QVariant
 %End
 
-    int outVertex() const;
+    int toVertex() const;
 %Docstring
- Returns index of the outgoing vertex
+ Returns the index of the vertex at the end of this edge.
+.. seealso:: fromVertex()
  :rtype: int
 %End
 
-    int inVertex() const;
+    int fromVertex() const;
 %Docstring
- Returns index of the incoming vertex
+ Returns the index of the vertex at the start of this edge.
+.. seealso:: toVertex()
  :rtype: int
 %End
 
@@ -62,6 +64,7 @@ class QgsGraphVertex
 {
 %Docstring
  This class implements a graph vertex
+.. versionadded:: 3.0
 %End
 
 %TypeHeaderCode
@@ -80,21 +83,23 @@ class QgsGraphVertex
  This constructor initializes QgsGraphVertex object and associates a vertex with a point
 %End
 
-    QgsGraphEdgeIds outEdges() const;
+    QgsGraphEdgeIds incomingEdges() const;
 %Docstring
- Returns outgoing edges ids
+ Returns the incoming edge ids, i.e. edges which end at this node.
+.. seealso:: outgoingEdges()
  :rtype: QgsGraphEdgeIds
 %End
 
-    QgsGraphEdgeIds inEdges() const;
+    QgsGraphEdgeIds outgoingEdges() const;
 %Docstring
- Return incoming edges ids
+ Returns outgoing edge ids, i.e. edges which start at this node.
+.. seealso:: incomingEdges()
  :rtype: QgsGraphEdgeIds
 %End
 
     QgsPointXY point() const;
 %Docstring
- Returns point associated with graph vertex
+ Returns point associated with graph vertex.
  :rtype: QgsPointXY
 %End
 
@@ -105,6 +110,7 @@ class QgsGraph
 {
 %Docstring
  Mathematical graph representation
+.. versionadded:: 3.0
 %End
 
 %TypeHeaderCode
@@ -124,9 +130,10 @@ class QgsGraph
  :rtype: int
 %End
 
-    int addEdge( int outVertexIdx, int inVertexIdx, const QVector< QVariant > &strategies );
+    int addEdge( int fromVertexIdx, int toVertexIdx, const QVector< QVariant > &strategies );
 %Docstring
- Add an edge to the graph
+ Add an edge to the graph, going from the ``fromVertexIdx``
+ to ``toVertexIdx``.
  :rtype: int
 %End
 

diff --git a/python/analysis/network/qgsgraphbuilder.sip b/python/analysis/network/qgsgraphbuilder.sip
@@ -30,12 +30,14 @@ class QgsGraphBuilder : QgsGraphBuilderInterface
     ~QgsGraphBuilder();
 
     virtual void addVertex( int id, const QgsPointXY &pt );
+
 %Docstring
  MANDATORY BUILDER PROPERTY DECLARATION
 %End
 
     virtual void addEdge( int pt1id, const QgsPointXY &pt1, int pt2id, const QgsPointXY &pt2, const QVector< QVariant > &prop );
 
+
     QgsGraph *graph() /Factory/;
 %Docstring
  Returns generated QgsGraph

diff --git a/python/plugins/processing/algs/qgis/ServiceAreaFromLayer.py b/python/plugins/processing/algs/qgis/ServiceAreaFromLayer.py
@@ -245,13 +245,13 @@ def processAlgorithm(self, parameters, context, feedback):
             tree, cost = QgsGraphAnalyzer.dijkstra(graph, idxStart, 0)
             for j, v in enumerate(cost):
                 if v > travelCost and tree[j] != -1:
-                    vertexId = graph.edge(tree[j]).outVertex()
+                    vertexId = graph.edge(tree[j]).toVertex()
                     if cost[vertexId] <= travelCost:
                         vertices.append(j)
 
             for j in vertices:
-                upperBoundary.append(graph.vertex(graph.edge(tree[j]).inVertex()).point())
-                lowerBoundary.append(graph.vertex(graph.edge(tree[j]).outVertex()).point())
+                upperBoundary.append(graph.vertex(graph.edge(tree[j]).fromVertex()).point())
+                lowerBoundary.append(graph.vertex(graph.edge(tree[j]).toVertex()).point())
 
             geomUpper = QgsGeometry.fromMultiPointXY(upperBoundary)
             geomLower = QgsGeometry.fromMultiPointXY(lowerBoundary)

diff --git a/python/plugins/processing/algs/qgis/ServiceAreaFromPoint.py b/python/plugins/processing/algs/qgis/ServiceAreaFromPoint.py
@@ -208,15 +208,15 @@ def processAlgorithm(self, parameters, context, feedback):
         vertices = []
         for i, v in enumerate(cost):
             if v > travelCost and tree[i] != -1:
-                vertexId = graph.edge(tree[i]).outVertex()
+                vertexId = graph.edge(tree[i]).toVertex()
                 if cost[vertexId] <= travelCost:
                     vertices.append(i)
 
         upperBoundary = []
         lowerBoundary = []
         for i in vertices:
-            upperBoundary.append(graph.vertex(graph.edge(tree[i]).inVertex()).point())
-            lowerBoundary.append(graph.vertex(graph.edge(tree[i]).outVertex()).point())
+            upperBoundary.append(graph.vertex(graph.edge(tree[i]).fromVertex()).point())
+            lowerBoundary.append(graph.vertex(graph.edge(tree[i]).toVertex()).point())
 
         feedback.pushInfo(self.tr('Writing results...'))
 

diff --git a/python/plugins/processing/algs/qgis/ShortestPathLayerToPoint.py b/python/plugins/processing/algs/qgis/ShortestPathLayerToPoint.py
@@ -233,7 +233,6 @@ def processAlgorithm(self, parameters, context, feedback):
 
             feedback.setProgress(int(current * total))
 
-
         feedback.pushInfo(self.tr('Building graph...'))
         snappedPoints = director.makeGraph(builder, points, feedback)
 
@@ -268,8 +267,8 @@ def processAlgorithm(self, parameters, context, feedback):
             current = idxEnd
             while current != idxStart:
                 cost += graph.edge(tree[current]).cost(0)
-                route.append(graph.vertex(graph.edge(tree[current]).inVertex()).point())
-                current = graph.edge(tree[current]).outVertex()
+                route.append(graph.vertex(graph.edge(tree[current]).fromVertex()).point())
+                current = graph.edge(tree[current]).toVertex()
 
             route.append(snappedPoints[i])
             route.reverse()

diff --git a/python/plugins/processing/algs/qgis/ShortestPathPointToLayer.py b/python/plugins/processing/algs/qgis/ShortestPathPointToLayer.py
@@ -267,8 +267,8 @@ def processAlgorithm(self, parameters, context, feedback):
             current = idxEnd
             while current != idxStart:
                 cost += graph.edge(tree[current]).cost(0)
-                route.append(graph.vertex(graph.edge(tree[current]).inVertex()).point())
-                current = graph.edge(tree[current]).outVertex()
+                route.append(graph.vertex(graph.edge(tree[current]).fromVertex()).point())
+                current = graph.edge(tree[current]).toVertex()
 
             route.append(snappedPoints[0])
             route.reverse()

diff --git a/python/plugins/processing/algs/qgis/ShortestPathPointToPoint.py b/python/plugins/processing/algs/qgis/ShortestPathPointToPoint.py
@@ -227,8 +227,8 @@ def processAlgorithm(self, parameters, context, feedback):
         current = idxEnd
         while current != idxStart:
             cost += graph.edge(tree[current]).cost(0)
-            route.append(graph.vertex(graph.edge(tree[current]).inVertex()).point())
-            current = graph.edge(tree[current]).outVertex()
+            route.append(graph.vertex(graph.edge(tree[current]).fromVertex()).point())
+            current = graph.edge(tree[current]).toVertex()
 
         route.append(snappedPoints[0])
         route.reverse()

diff --git a/src/analysis/network/qgsgraph.cpp b/src/analysis/network/qgsgraph.cpp
@@ -26,18 +26,18 @@ int QgsGraph::addVertex( const QgsPointXY &pt )
   return mGraphVertices.size() - 1;
 }
 
-int QgsGraph::addEdge( int outVertexIdx, int inVertexIdx, const QVector< QVariant > &strategies )
+int QgsGraph::addEdge( int fromVertexIdx, int toVertexIdx, const QVector< QVariant > &strategies )
 {
   QgsGraphEdge e;
 
   e.mStrategies = strategies;
-  e.mOut = outVertexIdx;
-  e.mIn  = inVertexIdx;
+  e.mToIdx = toVertexIdx;
+  e.mFromIdx  = fromVertexIdx;
   mGraphEdges.push_back( e );
   int edgeIdx = mGraphEdges.size() - 1;
 
-  mGraphVertices[ outVertexIdx ].mOutEdges.push_back( edgeIdx );
-  mGraphVertices[ inVertexIdx ].mInEdges.push_back( edgeIdx );
+  mGraphVertices[ toVertexIdx ].mIncomingEdges.push_back( edgeIdx );
+  mGraphVertices[ fromVertexIdx ].mOutgoingEdges.push_back( edgeIdx );
 
   return mGraphEdges.size() - 1;
 }
@@ -85,14 +85,14 @@ QVector< QVariant > QgsGraphEdge::strategies() const
   return mStrategies;
 }
 
-int QgsGraphEdge::inVertex() const
+int QgsGraphEdge::fromVertex() const
 {
-  return mIn;
+  return mFromIdx;
 }
 
-int QgsGraphEdge::outVertex() const
+int QgsGraphEdge::toVertex() const
 {
-  return mOut;
+  return mToIdx;
 }
 
 QgsGraphVertex::QgsGraphVertex( const QgsPointXY &point )
@@ -101,14 +101,14 @@ QgsGraphVertex::QgsGraphVertex( const QgsPointXY &point )
 
 }
 
-QgsGraphEdgeIds QgsGraphVertex::outEdges() const
+QgsGraphEdgeIds QgsGraphVertex::incomingEdges() const
 {
-  return mOutEdges;
+  return mIncomingEdges;
 }
 
-QgsGraphEdgeIds QgsGraphVertex::inEdges() const
+QgsGraphEdgeIds QgsGraphVertex::outgoingEdges() const
 {
-  return mInEdges;
+  return mOutgoingEdges;
 }
 
 QgsPointXY QgsGraphVertex::point() const

diff --git a/src/analysis/network/qgsgraph.h b/src/analysis/network/qgsgraph.h
@@ -61,21 +61,23 @@ class ANALYSIS_EXPORT QgsGraphEdge
     QVector< QVariant > strategies() const;
 
     /**
-     * Returns index of the outgoing vertex
+     * Returns the index of the vertex at the end of this edge.
+     * \see fromVertex()
      */
-    int outVertex() const;
+    int toVertex() const;
 
     /**
-     * Returns index of the incoming vertex
+     * Returns the index of the vertex at the start of this edge.
+     * \see toVertex()
      */
-    int inVertex() const;
+    int fromVertex() const;
 
   private:
 
     QVector< QVariant > mStrategies;
 
-    int mOut = 0;
-    int mIn = 0;
+    int mToIdx = 0;
+    int mFromIdx = 0;
 
     friend class QgsGraph;
 };
@@ -87,6 +89,7 @@ typedef QList< int > QgsGraphEdgeIds;
  * \ingroup analysis
  * \class QgsGraphVertex
  * \brief This class implements a graph vertex
+ * \since QGIS 3.0
  */
 class ANALYSIS_EXPORT QgsGraphVertex
 {
@@ -104,24 +107,26 @@ class ANALYSIS_EXPORT QgsGraphVertex
     QgsGraphVertex( const QgsPointXY &point );
 
     /**
-     * Returns outgoing edges ids
+     * Returns the incoming edge ids, i.e. edges which end at this node.
+     * \see outgoingEdges()
      */
-    QgsGraphEdgeIds outEdges() const;
+    QgsGraphEdgeIds incomingEdges() const;
 
     /**
-     * Return incoming edges ids
+     * Returns outgoing edge ids, i.e. edges which start at this node.
+     * \see incomingEdges()
      */
-    QgsGraphEdgeIds inEdges() const;
+    QgsGraphEdgeIds outgoingEdges() const;
 
     /**
-     * Returns point associated with graph vertex
+     * Returns point associated with graph vertex.
      */
     QgsPointXY point() const;
 
   private:
     QgsPointXY mCoordinate;
-    QgsGraphEdgeIds mOutEdges;
-    QgsGraphEdgeIds mInEdges;
+    QgsGraphEdgeIds mIncomingEdges;
+    QgsGraphEdgeIds mOutgoingEdges;
 
     friend class QgsGraph;
 };
@@ -130,6 +135,7 @@ class ANALYSIS_EXPORT QgsGraphVertex
  * \ingroup analysis
  * \class QgsGraph
  * \brief Mathematical graph representation
+ * \since QGIS 3.0
  */
 
 class ANALYSIS_EXPORT QgsGraph
@@ -149,9 +155,10 @@ class ANALYSIS_EXPORT QgsGraph
     int addVertex( const QgsPointXY &pt );
 
     /**
-     * Add an edge to the graph
+     * Add an edge to the graph, going from the \a fromVertexIdx
+     * to \a toVertexIdx.
      */
-    int addEdge( int outVertexIdx, int inVertexIdx, const QVector< QVariant > &strategies );
+    int addEdge( int fromVertexIdx, int toVertexIdx, const QVector< QVariant > &strategies );
 
     /**
      * Returns number of graph vertices

diff --git a/src/analysis/network/qgsgraphanalyzer.cpp b/src/analysis/network/qgsgraphanalyzer.cpp
@@ -59,21 +59,21 @@ void QgsGraphAnalyzer::dijkstra( const QgsGraph *source, int startPointIdx, int
     not_begin.erase( it );
 
     // edge index list
-    QgsGraphEdgeIds l = source->vertex( curVertex ).outEdges();
+    QgsGraphEdgeIds l = source->vertex( curVertex ).incomingEdges();
     QgsGraphEdgeIds::iterator arcIt;
     for ( arcIt = l.begin(); arcIt != l.end(); ++arcIt )
     {
       const QgsGraphEdge arc = source->edge( *arcIt );
       double cost = arc.cost( criterionNum ).toDouble() + curCost;
 
-      if ( cost < ( *result )[ arc.inVertex()] )
+      if ( cost < ( *result )[ arc.fromVertex()] )
       {
-        ( *result )[ arc.inVertex()] = cost;
+        ( *result )[ arc.fromVertex()] = cost;
         if ( resultTree )
         {
-          ( *resultTree )[ arc.inVertex()] = *arcIt;
+          ( *resultTree )[ arc.fromVertex()] = *arcIt;
         }
-        not_begin.insert( cost, arc.inVertex() );
+        not_begin.insert( cost, arc.fromVertex() );
       }
     }
   }
@@ -111,7 +111,7 @@ QgsGraph *QgsGraphAnalyzer::shortestTree( const QgsGraph *source, int startVerte
     {
       const QgsGraphEdge &arc = source->edge( tree[i] );
 
-      treeResult->addEdge( source2result[ arc.outVertex()], source2result[ arc.inVertex()],
+      treeResult->addEdge( source2result[ arc.fromVertex()], source2result[ arc.toVertex()],
                            arc.strategies() );
     }
   }

diff --git a/src/analysis/network/qgsgraphbuilder.cpp b/src/analysis/network/qgsgraphbuilder.cpp
@@ -42,7 +42,7 @@ void QgsGraphBuilder::addVertex( int, const QgsPointXY &pt )
 
 void QgsGraphBuilder::addEdge( int pt1id, const QgsPointXY &, int pt2id, const QgsPointXY &, const QVector< QVariant > &prop )
 {
-  mGraph->addEdge( pt1id, pt2id, prop );
+  mGraph->addEdge( pt2id, pt1id, prop );
 }
 
 QgsGraph *QgsGraphBuilder::graph()

diff --git a/src/analysis/network/qgsgraphbuilder.h b/src/analysis/network/qgsgraphbuilder.h
@@ -46,9 +46,9 @@ class ANALYSIS_EXPORT QgsGraphBuilder : public QgsGraphBuilderInterface
     /*
      * MANDATORY BUILDER PROPERTY DECLARATION
      */
-    virtual void addVertex( int id, const QgsPointXY &pt ) override;
+    void addVertex( int id, const QgsPointXY &pt ) override;
 
-    virtual void addEdge( int pt1id, const QgsPointXY &pt1, int pt2id, const QgsPointXY &pt2, const QVector< QVariant > &prop ) override;
+    void addEdge( int pt1id, const QgsPointXY &pt1, int pt2id, const QgsPointXY &pt2, const QVector< QVariant > &prop ) override;
 
     /**
      * Returns generated QgsGraph