New function : biconnected planar

NEWS.md

@@ -35,12 +35,22 @@ To see all issues & pull requests closed by this release see the
 * [#3101](https://github.com/pgRouting/pgrouting/issues/3101): pgr_edgeColoring not building graph correctly
 
 
+**New experimental functions.**
+
+* Planar
+
+  * pgr_makeBiconnectedPlanar
+
 **Summary of changes by function**
 
 * pgr_edgeColoring
 
   * Fix the way it builds the graph
 
+* pgr_makeBiconnectedPlanar
+
+  * New experimental function.
+
 ## pgRouting 4.0
 
 

doc/_static/page_history.js

@@ -16,6 +16,8 @@ var titles = [
 
 
 var newpages = [
+    {v: '4.1', pages: ['pgr_makeBiconnectedPlanar']},
+
     {v: '4.0', pages: ['pgr_bandwidth', 'pgr_kingOrdering', 'pgr_sloanOrdering']},
 
     {v: '3.8', pages: ['pgr_contractionDeadEnd', 'pgr_contractionLinear', 'pgr_separateCrossing',

doc/planar/CMakeLists.txt

@@ -3,7 +3,9 @@
 # License: GPL-2 See https://github.com/pgRouting/pgrouting/blob/main/LICENSE
 
 set(LOCAL_FILES
+    planar-family.rst
     pgr_isPlanar.rst
+    pgr_makeBiconnectedPlanar.rst
     )
 
 foreach (f ${LOCAL_FILES})

doc/planar/images/CMakeLists.txt

@@ -3,6 +3,9 @@
 # License: GPL-2 See https://github.com/pgRouting/pgrouting/blob/main/LICENSE
 set(LOCAL_FILES
     nonPlanar.png
+    biconnected_planar_sampledata.png
+    biconnected_line_before.png
+    biconnected_line_after.png
     )
 
 foreach (f ${LOCAL_FILES})

doc/planar/pgr_makeBiconnectedPlanar.rst

@@ -0,0 +1,164 @@
+:file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2020-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0
+
+.. index::
+   single: Planar Family ; pgr_makeBiconnectedPlanar - Experimental
+   single: makeBiconnectedPlanar - Experimental on v4.1
+
+|
+
+``pgr_makeBiconnectedPlanar`` - Experimental
+===============================================================================
+
+``pgr_makeBiconnectedPlanar`` — Returns the set of edges needed to make each connected component of a planar graph biconnected.
+
+.. include:: experimental.rst
+   :start-after: warning-begin
+   :end-before: end-warning
+
+.. rubric:: Availability
+
+.. rubric:: Version 4.1.0
+
+* New experimental function.
+
+
+Description
+-------------------------------------------------------------------------------
+
+``pgr_makeBiconnectedPlanar`` identifies the missing edges that need to be added to each
+connected component of an existing planar graph to make those components biconnected,
+while ensuring the graph remains planar.
+
+A graph is considered **biconnected** if it is connected and cannot be broken into
+disconnected pieces by deleting any single vertex (it has no articulation points).
+A planar graph is one that can be drawn in two-dimensional space with no two of
+its edges crossing.
+
+The main characteristics are:
+
+* Works for **undirected** graphs.
+* Works for **planar** graphs only.
+* If any component of the input graph is not planar, no added edges are returned for that component.
+* Returns a list of all new edges needed to make each connected component of the graph biconnected.
+* The algorithm does not consider traversal costs in the calculations.
+* The algorithm does not consider geometric topology in the calculations.
+* Running time: :math:`O(|V_G| + |E_G| + R \log R)` where :math:`G(V_G, E_G)` is the input graph and :math:`R` is the number of returned edges.
+
+|Boost| Boost Graph Inside
+
+Signatures
+-------------------------------------------------------------------------------
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_makeBiconnectedPlanar(`Edges SQL`_)
+
+   | Returns set of |result-component-make|
+   | OR EMPTY SET
+
+:Example: List of edges that are needed to make the graph biconnected planar.
+
+**Sample graph before:**
+
+.. figure:: /images/Fig6-undirected.png
+   :scale: 50%
+
+   Sample graph before
+
+**Output:**
+
+.. literalinclude:: makeBiconnectedPlanar.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+**Sample graph after adding biconnecting edges:**
+
+.. figure:: images/biconnected_planar_sampledata.png
+   :scale: 75%
+
+   Sample graph after adding biconnecting edges (olive = original edges, red dashed = 4 new biconnecting edges).
+   Note: When a graph contains multiple disconnected components, each component is processed independently. Components (2,4) and (13,14) are already biconnected (0 articulation points) and require no new edges.
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+   :start-after: only_edge_param_start
+   :end-before: only_edge_param_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_edges_sql_start
+    :end-before: basic_edges_sql_end
+
+Result columns
+-------------------------------------------------------------------------------
+
+Returns set of |result-component-make|
+
+.. list-table::
+   :width: 81
+   :widths: auto
+   :header-rows: 1
+
+   * - Column
+     - Type
+     - Description
+   * - ``seq``
+     - ``BIGINT``
+     - Sequential value starting from **1**.
+   * - ``start_vid``
+     - ``BIGINT``
+     - Identifier of the first end point vertex of the edge.
+   * - ``end_vid``
+     - ``BIGINT``
+     - Identifier of the second end point vertex of the edge.
+
+Additional Examples
+-------------------------------------------------------------------------------
+
+:Example: Biconnecting a simple 4-vertex line graph (path graph).
+
+.. literalinclude:: makeBiconnectedPlanar.queries
+   :start-after: -- q2
+   :end-before: -- q3
+
+**Sample graph before:**
+
+.. figure:: images/biconnected_line_before.png
+   :scale: 75%
+
+   Sample 4-vertex line graph before biconnecting (vertices 2 and 3 are articulation points).
+
+**Output:**
+
+.. literalinclude:: makeBiconnectedPlanar.queries
+   :start-after: -- q3
+   :end-before: -- q4
+
+**Sample graph after adding biconnecting edges:**
+
+.. figure:: images/biconnected_line_after.png
+   :scale: 75%
+
+   Biconnected planar graph after adding new edges to eliminate articulation points without crossing.
+
+See Also
+-------------------------------------------------------------------------------
+
+* `Boost: make_biconnected_planar
+  <https://www.boost.org/doc/libs/latest/libs/graph/doc/html/graph/algorithms/planar/make_biconnected_planar.html>`__
+* :doc:`sampledata`
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/planar/planar-family.rst

@@ -0,0 +1,33 @@
+:file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2020-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0
+
+.. index:: Planar Family 
+
+|
+
+Planar - Family of functions
+===============================================================================
+
+.. include:: experimental.rst
+   :start-after: warning-begin
+   :end-before: end-warning
+
+.. experimental-start
+
+* :doc:`pgr_isPlanar` - Returns a boolean depending upon the planarity of the graph.
+* :doc:`pgr_makeBiconnectedPlanar` - Returns edges to add to a planar graph to make each connected component biconnected.
+
+.. experimental-end
+
+
+.. toctree::
+    :hidden:
+
+    pgr_isPlanar
+    pgr_makeBiconnectedPlanar
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/src/experimental.rst

@@ -129,12 +129,12 @@ Experimental Functions
 
 .. rubric:: Planar Family
 
-- :doc:`pgr_isPlanar`
+- :doc:`planar-family`
 
 .. toctree::
   :hidden:
 
-  pgr_isPlanar
+  planar-family
 
 .. rubric:: Miscellaneous Algorithms
 

doc/src/release_notes.rst

@@ -60,6 +60,12 @@ To see all issues & pull requests closed by this release see the
 * :issue:`3101`: pgr_edgeColoring not building graph correctly
 
 
+.. rubric:: New experimental functions.
+
+* Planar
+
+  * pgr_makeBiconnectedPlanar
+
 .. rubric:: Summary of changes by function
 
 * pgr_edgeColoring
@@ -68,6 +74,12 @@ To see all issues & pull requests closed by this release see the
      :start-after: Version 4.1.0
      :end-before: .. rubric
 
+* pgr_makeBiconnectedPlanar
+
+  .. include:: pgr_makeBiconnectedPlanar.rst
+     :start-after: Version 4.1.0
+     :end-before: Description
+
 pgRouting 4.0
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 

docqueries/planar/CMakeLists.txt

@@ -5,6 +5,7 @@
 set(LOCAL_FILES
     boyerMyrvold
     isPlanar
+    makeBiconnectedPlanar
     )
 
 foreach (f ${LOCAL_FILES})

docqueries/planar/makeBiconnectedPlanar.pg

@@ -0,0 +1,25 @@
+/* :file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2020-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0 */
+/* -- q1 */
+SELECT * FROM pgr_makeBiconnectedPlanar(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+);
+/* -- q2 */
+CREATE TABLE example_edges_bi (
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+INSERT INTO example_edges_bi (source, target, cost, reverse_cost) VALUES
+(1, 2, 1, 1),
+(2, 3, 1, 1),
+(3, 4, 1, 1);
+
+/* -- q3 */
+SELECT * FROM pgr_makeBiconnectedPlanar(
+  'SELECT id, source, target, cost, reverse_cost FROM example_edges_bi'
+);
+/* -- q4 */

docqueries/planar/makeBiconnectedPlanar.result

@@ -0,0 +1,46 @@
+BEGIN;
+BEGIN
+SET client_min_messages TO NOTICE;
+SET
+/* :file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2020-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0 */
+/* -- q1 */
+SELECT * FROM pgr_makeBiconnectedPlanar(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+);
+ seq | start_vid | end_vid
+-----+-----------+---------
+   1 |         1 |       7
+   2 |         3 |      11
+   3 |         5 |      10
+   4 |         7 |       9
+(4 rows)
+
+/* -- q2 */
+CREATE TABLE example_edges_bi (
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+CREATE TABLE
+INSERT INTO example_edges_bi (source, target, cost, reverse_cost) VALUES
+(1, 2, 1, 1),
+(2, 3, 1, 1),
+(3, 4, 1, 1);
+INSERT 0 3
+/* -- q3 */
+SELECT * FROM pgr_makeBiconnectedPlanar(
+  'SELECT id, source, target, cost, reverse_cost FROM example_edges_bi'
+);
+ seq | start_vid | end_vid
+-----+-----------+---------
+   1 |         1 |       3
+   2 |         2 |       4
+(2 rows)
+
+/* -- q4 */
+ROLLBACK;
+ROLLBACK

docqueries/planar/test.conf

@@ -7,6 +7,7 @@
     'any' => {
         'files' => [qw(
             isPlanar.pg
+            makeBiconnectedPlanar.pg
             )]
     },
 

include/c_common/enums.h

@@ -52,6 +52,8 @@ enum Which {  // NOLINT(cppcoreguidelines-use-enum-class)
     MAXFLOW, PUSHRELABEL, BOYKOV, EDMONDSKARP,
     /* For coloring */
     EDGECOLORING, BIPARTITE, SEQUENTIAL,
+    /* For planar */
+    BICONNECTEDPLANAR,
     /* For components */
     CONNECTEDCOMPONENTS, BICONNECTEDCOMPONENTS, STRONGCOMPONENTS, ARTICULATIONPOINTS,
     BRIDGES, MAKECONNECTED