Port new function pgr_separateTouching from 2855

NEWS.md

@@ -180,6 +180,8 @@ milestone for 3.8.0
 
   * [#2848](https://github.com/pgRouting/pgrouting/issues/2848):
     pgr_separateCrossing
+  * [#2849](https://github.com/pgRouting/pgrouting/issues/2849):
+    pgr_separateTouching
 
 ## pgRouting 3.7
 

doc/_static/page_history.js

@@ -15,7 +15,8 @@ var titles = [
 
 
 var newpages = [
-    {v: '3.8', pages: ['pgr_contractionDeadEnd', 'pgr_contractionLinear', 'pgr_separateCrossing']},
+    {v: '3.8', pages: ['pgr_contractionDeadEnd', 'pgr_contractionLinear', 'pgr_separateCrossing',
+        'pgr_separateTouching']},
 
     {v: '3.7', pages: ['metrics-family', 'pgr_betweennessCentrality']},
 

doc/src/images/CMakeLists.txt

@@ -1,6 +1,7 @@
 
 SET(LOCAL_FILES
     crossing_edges.png
+    touching_edges.png
     Dijkstra_Animation.gif
     )
 

doc/src/pgRouting-concepts.rst

@@ -18,7 +18,7 @@ with pgRouting. This guide covers:
 
 .. contents::
     :local:
-    :depth: 1
+    :depth: 2
 
 Graphs
 -------------------------------------------------------------------------------
@@ -669,87 +669,102 @@ removed and the routing topology needs to be updated.
    :start-after: fix_intersection_start
    :end-before: fix_intersection_end
 
-Disconnected graphs
+Touching edges
 ...............................................................................
 
-.. connecting_graph_start
+Visually the edges seem to be connected, but internally they are not.
+
+.. literalinclude:: concepts.queries
+   :start-after: -- touch1
+   :end-before: -- touch2
+
+.. figure:: images/touching_edges.png
+
+The validity of the information is application dependent.
+
+- Maybe there is a small barrier for vehicles but not for pedestrians.
+
+Once analyzed one by one the touchings, for the ones that need a local fix,
+the edges need to be `split <https://postgis.net/docs/ST_Split.html>`__.
+
+The new edges need to be added to the edges table, the rest of the attributes
+need to be updated in the new edges, the old edges need to be
+removed and the routing topology needs to be updated.
 
-.. disconnected_graph_start
+.. include:: pgr_separateTouching.rst
+   :start-after: fix_gap-start
+   :end-before: fix_gap-end
+
+Connecting components
+...............................................................................
+
+.. connecting_graph_start
 
 To get the graph connectivity:
 
 .. literalinclude:: concepts.queries
    :start-after: -- connect2
    :end-before: -- connect3
 
-In this example, the component :math:`2` consists of vertices :math:`\{2, 4\}`
-and both vertices are also part of the dead end result set.
+There are three basic ways to connect components:
+
+* From the vertex to the starting point of the edge
+* From the vertex to the ending point of the edge
+* From the vertex to the closest vertex on the edge
 
-.. disconnected_graph_end
+  * This solution requires the edge to be split.
 
-This graph needs to be connected.
+In this example :doc:`pgr_separateCrossing` and :doc:`pgr_separateTouching` will
+be used.
 
-.. Note::
-   With the original graph of this documentation, there would be 3 components as
-   the crossing edge in this graph is a different component.
+.. rubric:: Get the connectivity
 
-Prepare storage for connection information
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. literalinclude:: concepts.queries
+   :start-after: -- connect2
+   :end-before: -- connect3
+
+.. rubric:: Prepare tables
+
+In this example: the edges table will need an additional column and the vertex
+table will be rebuilt completely.
 
 .. literalinclude:: concepts.queries
    :start-after: -- connect3
    :end-before: -- connect4
 
-Save the vertices connection information
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. rubric:: Insert new edges
+
+Using :doc:`pgr_separateCrossing` and :doc:`pgr_separateTouching` insert the
+results into the edges table.
 
 .. literalinclude:: concepts.queries
    :start-after: -- connect4
    :end-before: -- connect5
 
-Save the edges connection information
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. rubric:: Create the vertices table
+
+Using :doc:`pgr_extractVertices` create the table.
 
 .. literalinclude:: concepts.queries
    :start-after: -- connect5
    :end-before: -- connect6
 
-Get the closest vertex
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Using :doc:`pgr_findCloseEdges` the closest vertex to component :math:`1` is
-vertex :math:`4`. And the closest edge to vertex :math:`4` is edge :math:`14`.
+.. rubric:: Update the topology
 
 .. literalinclude:: concepts.queries
    :start-after: -- connect6
    :end-before: -- connect7
 
-The ``edge`` can be used to connect the components, using the ``fraction``
-information about the edge :math:`14` to split the connecting edge.
-
-Connecting components
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-There are three basic ways to connect the components
-
-* From the vertex to the starting point of the edge
-* From the vertex to the ending point of the edge
-* From the vertex to the closest vertex on the edge
-
-  * This solution requires the edge to be split.
+.. rubric:: Update other values
 
-The following query shows the three ways to connect the components:
+In this example only ``cost`` and ``reverse_cost`` are updated, where they are
+based on the length of the geometry and the directionality is kept using the
+``sign`` function.
 
 .. literalinclude:: concepts.queries
    :start-after: -- connect7
    :end-before: -- connect8
 
-Checking components
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Ignoring the edge that requires further work. The graph is now fully connected
-as there is only one component.
-
 .. literalinclude:: concepts.queries
    :start-after: -- connect8
    :end-before: -- connect9

doc/src/release_notes.rst

@@ -219,6 +219,8 @@ milestone for 3.8.0
 
   * `#2848 <https://github.com/pgRouting/pgrouting/issues/2848>`__:
     pgr_separateCrossing
+  * `#2849 <https://github.com/pgRouting/pgrouting/issues/2849>`__:
+    pgr_separateTouching
 
 pgRouting 3.7
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

doc/topology/topology-functions.rst

@@ -53,6 +53,7 @@ Utility functions
 .. utility_proposed-start
 
 - :doc:`pgr_separateCrossing` - Breaks geometries that cross each other.
+- :doc:`pgr_separateTouching` - Breaks geometries that (almost) touch each other.
 
 .. utility_proposed-end
 
@@ -63,6 +64,7 @@ Utility functions
   pgr_extractVertices
   pgr_findCloseEdges
   pgr_separateCrossing
+  pgr_separateTouching
 
 See Also
 -------------------------------------------------------------------------------

doc/utilities/CMakeLists.txt

@@ -1,6 +1,7 @@
 SET(LOCAL_FILES
     pgr_findCloseEdges.rst
     pgr_separateCrossing.rst
+    pgr_separateTouching.rst
     )
 
 foreach (f ${LOCAL_FILES})

doc/utilities/pgr_separateCrossing.rst

@@ -70,7 +70,7 @@ Inner Queries
 -------------------------------------------------------------------------------
 
 Edges SQL
-...............................................................................
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 ================= =================== ===================================
 Column            Type                Description
@@ -86,7 +86,7 @@ Examples
    :local:
 
 Get the code for further refinement.
-...............................................................................
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 When there are special details that need to be taken care of because of the
 final application or the quality of the data, the code can be obtained On a
@@ -99,60 +99,57 @@ PostgreSQL ``NOTICE`` using the ``dryrun`` flag.
 .. fix_intersection_start
 
 Fixing an intersection
-...............................................................................
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 In this example the original edge table will be used to store the additional
 geometries.
 
-Create the topology for the data in :doc:`sampledata`
+.. rubric:: An example use without results
 
-.. literalinclude:: sampledata.queries
-   :start-after: -- q1
-   :end-before: -- q1-1
-
-.. literalinclude:: sampledata.queries
-   :start-after: -- q3
-   :end-before: -- q4
-
-Routing from :math:`1` to :math:`2` gives no solution.
+Routing from :math:`1` to :math:`18` gives no solution.
 
 .. literalinclude:: separateCrossing.queries
    :start-after: --q3
    :end-before: --q4
 
-Analyze the network for intersections.
+.. rubric:: Analyze the network for intersections.
 
 .. literalinclude:: separateCrossing.queries
    :start-after: --q4
    :end-before: --q5
 
 The analysis tell us that the network has an intersection.
 
+.. rubric:: Prepare tables
 
 Additional columns to control the origin of the segments.
 
 .. literalinclude:: separateCrossing.queries
    :start-after: --q5
    :end-before: --q6
 
-Calling :doc:`pgr_separateCrossing` and adding the new segments to the edges table.
+.. rubric:: Adding new segments.
+
+Calling :doc:`pgr_separateCrossing` and adding the new segments to the edges
+table.
 
 .. literalinclude:: separateCrossing.queries
    :start-after: --q6
    :end-before: --q7
 
-Update the cost and reverse_cost values.
+.. rubric:: Update other values
 
-In this example the costs are based on the length of the geometry and the
-directionality is kept using the ``sign`` function.
+In this example only ``cost`` and ``reverse_cost`` are updated, where they are
+based on the length of the geometry and the directionality is kept using the
+``sign`` function.
 
 .. literalinclude:: separateCrossing.queries
    :start-after: --q7
    :end-before: --q8
 
 .. rubric:: Update the topology
 
-Insert the intersections as new vertices.
+Insert the new vertices if any.
 
 .. literalinclude:: separateCrossing.queries
    :start-after: --q8
@@ -164,6 +161,8 @@ Update source and target information on the edges table.
    :start-after: --q9
    :end-before: --q10
 
+.. rubric:: The example has results
+
 Routing from :math:`1` to :math:`18` gives a solution.
 
 .. literalinclude:: separateCrossing.queries