Add procedure and docs for water routing prep.

Author: rustprooflabs

db/deploy/routing_functions.sql

@@ -317,8 +317,8 @@ BEGIN
         STORED
     ;
 
-    COMMENT ON COLUMN {schema_name}.routing_road_edge.cost_length_forward IS 'Length based cost for forward travel when using directed travel graphs.';
-    COMMENT ON COLUMN {schema_name}.routing_road_edge.cost_length_reverse IS 'Length based cost for reverse travel when using directed travel graphs.';
+    COMMENT ON COLUMN {schema_name}.routing_road_edge.cost_length_forward IS 'Length based cost for forward travel with directed routing. Based on cost_length value.';
+    COMMENT ON COLUMN {schema_name}.routing_road_edge.cost_length_reverse IS 'Length based cost for reverse travel with directed routing. Based on cost_length value.';
 
 
     DROP TABLE IF EXISTS {schema_name}.routing_road_vertex;
@@ -369,3 +369,143 @@ END $$;
 
 
 COMMENT ON PROCEDURE {schema_name}.routing_prepare_roads IS 'Creates the {schema_name}.routing_road_edge and {schema_name}.routing_road_vertex from the {schema_name}.road_line input data';
+
+
+
+--------------------------------------------------
+-- Waterway routing prep
+--------------------------------------------------
+
+
+CREATE OR REPLACE PROCEDURE {schema_name}.routing_prepare_water()
+LANGUAGE plpgsql
+AS $$
+BEGIN
+
+    CALL {schema_name}.pgrouting_version_check();
+
+    --Create edges table for input to routing_prepare_edges procedure
+    DROP TABLE IF EXISTS route_edge_input;
+    CREATE TEMP TABLE route_edge_input AS
+    SELECT osm_id, layer, geom
+        FROM {schema_name}.water_line
+    ;
+
+    -- Creates the `route_edges_output` table.
+    CALL {schema_name}.routing_prepare_edges();
+
+
+    DROP TABLE IF EXISTS {schema_name}.routing_water_edge;
+    CREATE TABLE {schema_name}.routing_water_edge
+    (
+        edge_id BIGINT NOT NULL GENERATED ALWAYS AS IDENTITY PRIMARY KEY
+        , osm_id BIGINT NOT NULL
+        , sub_id BIGINT NOT NULL
+        , vertex_id_source BIGINT
+        , vertex_id_target BIGINT
+        , layer INT
+        , osm_type TEXT NOT NULL
+        , name TEXT
+        , tunnel TEXT
+        , bridge TEXT
+        , geom GEOMETRY(LINESTRING)
+    );
+
+    INSERT INTO {schema_name}.routing_water_edge (
+        osm_id, sub_id, osm_type, name, layer, tunnel, bridge
+        , geom
+    )
+    SELECT re.osm_id, re.sub_id
+            , r.osm_type, r.name
+            , re.layer, r.tunnel, r.bridge
+            , re.geom
+        FROM route_edges_output re
+        INNER JOIN {schema_name}.water_line r ON re.osm_id = r.osm_id
+        ORDER BY re.geom
+    ;
+
+    CREATE INDEX gix_{schema_name}_routing_water_edge
+        ON {schema_name}.routing_water_edge
+        USING GIST (geom)
+    ;
+
+    RAISE NOTICE 'Created table {schema_name}.routing_water_edge with edge data';
+
+
+    ALTER TABLE {schema_name}.routing_water_edge
+        ADD cost_length DOUBLE PRECISION NULL;
+
+    UPDATE {schema_name}.routing_water_edge
+        SET cost_length = ST_Length(ST_Transform(geom, 4326)::GEOGRAPHY)
+    ;
+
+    COMMENT ON COLUMN {schema_name}.routing_water_edge.cost_length IS 'Length based cost calculated using GEOGRAPHY for accurate length.';
+
+
+    -- Add forward cost column, enforcing oneway restrictions
+    ALTER TABLE {schema_name}.routing_water_edge
+        ADD cost_length_forward NUMERIC
+        GENERATED ALWAYS AS (cost_length)
+        STORED
+    ;
+
+    -- Add reverse cost column, enforcing oneway restrictions
+    ALTER TABLE {schema_name}.routing_water_edge
+        ADD cost_length_reverse NUMERIC
+        GENERATED ALWAYS AS (-1 * cost_length)
+        STORED
+    ;
+
+    COMMENT ON COLUMN {schema_name}.routing_water_edge.cost_length_forward IS 'Length based cost for forward travel with directed routing. Based on cost_length value.';
+    COMMENT ON COLUMN {schema_name}.routing_water_edge.cost_length_reverse IS 'Length based cost for reverse travel with directed routing. Based on cost_length value.';
+
+
+    DROP TABLE IF EXISTS {schema_name}.routing_water_vertex;
+    CREATE TABLE {schema_name}.routing_water_vertex AS
+    SELECT  * FROM pgr_extractVertices(
+    'SELECT edge_id AS id, geom FROM {schema_name}.routing_water_edge')
+    ;
+    RAISE NOTICE 'Created table {schema_name}.routing_water_vertex from edges.';
+
+    CREATE INDEX gix_{schema_name}_routing_water_vertex
+        ON {schema_name}.routing_water_vertex
+        USING GIST (geom)
+    ;
+
+    --  Update source column from out_edges
+    WITH outgoing AS (
+        SELECT id AS vertex_id_source
+            , unnest(out_edges) AS edge_id
+    FROM {schema_name}.routing_water_vertex
+    )
+    UPDATE {schema_name}.routing_water_edge e
+    SET vertex_id_source = o.vertex_id_source
+    FROM outgoing o
+    WHERE e.edge_id = o.edge_id
+        AND e.vertex_id_source IS NULL
+    ;
+
+    -- Update target column from in_edges
+    WITH incoming AS (
+        SELECT id AS vertex_id_target
+            , unnest(in_edges) AS edge_id
+    FROM {schema_name}.routing_water_vertex
+    )
+    UPDATE {schema_name}.routing_water_edge e
+    SET vertex_id_target = i.vertex_id_target
+    FROM incoming i
+    WHERE e.edge_id = i.edge_id
+        AND e.vertex_id_target IS NULL
+    ;
+
+
+    ANALYZE {schema_name}.routing_water_edge;
+    ANALYZE {schema_name}.routing_water_vertex;
+
+    COMMENT ON TABLE {schema_name}.routing_water_vertex IS 'Routing vertex data. These points can be used as the start/end points for routing the edge network in {schema_name}.routing_water_edge..';
+
+
+END $$;
+
+
+COMMENT ON PROCEDURE {schema_name}.routing_prepare_water IS 'Creates the {schema_name}.routing_water_edge and {schema_name}.routing_water_vertex from the {schema_name}.water_line input data';

docs/src/dc-water-route-example.png

@@ -87,17 +87,8 @@ This direction data type resolves to `int2` in Postgres. Valid values are:
 * `-1`: One way, reverse travel allowed
 * `NULL`: It's complicated. See [#172](https://github.com/rustprooflabs/pgosm-flex/issues/172).
 
-The `osm.routing_road_edge` table has the `oneway` column from the
-`osm.road_line` table used as the source.
-
-
-Forward and reverse cost columns are calculated within the
-`osm.routing_prepare_roads()` procedure.
-
-
-Calculate forward and reverse costs using the `oneway` column. This still provides
-a length-based cost. The change is to also enforce direction restrictions within
-the cost model.
+> Forward and reverse cost columns are calculated in the `cost_length_forward`
+> and `cost_length_reverse` columns within the `osm.routing_prepare_roads()` procedure.
 
 
 ## Travel Time Costs
@@ -262,7 +253,7 @@ SELECT d.*, n.geom AS node_geom, e.geom AS edge_geom
 
 ![Screenshot from DBeaver showing the route generated with all roads and limiting based on route_motor. The route bypasses the road(s) marked access=no and access=private.](dc-example-route-start-motor-access-control.png)
 
-# Oneway-aware routing
+# One-way Aware Routing
 
 The route shown in the previous example now respects the
 access control and limits to routes suitable for motorized traffic.
@@ -299,3 +290,84 @@ SELECT d.*, n.geom AS node_geom, e.geom AS edge_geom
 
 ![Screenshot from DBeaver showing the route generated with all roads and limiting based on route_motor and using the improved cost model including forward and reverse costs. The route bypasses the road(s) marked access=no and access=private, as well as respects the one-way access controls.](dc-example-route-start-motor-access-control-oneway.png)
 
+
+# Routing with Water
+
+PgOSM Flex also includes a procedure to prepare a routing network using
+the `osm.water_line` table.
+
+```sql
+CALL osm.routing_prepare_water();
+```
+
+Find the `vertex_id` for start and end nodes, similar to approach above
+with roads.
+
+```sql
+
+WITH s_point AS (
+SELECT v.id AS start_id, v.geom
+    FROM osm.routing_water_vertex v
+    INNER JOIN (SELECT
+        ST_Transform(ST_SetSRID(ST_MakePoint(-77.050625, 38.908953), 4326), 3857)
+            AS geom
+        ) p ON v.geom <-> p.geom < 200
+    ORDER BY v.geom <-> p.geom
+    LIMIT 1
+), e_point AS (
+SELECT v.id AS end_id, v.geom
+    FROM osm.routing_water_vertex v
+    INNER JOIN (SELECT
+        ST_Transform(ST_SetSRID(ST_MakePoint(-77.055645, 38.888747), 4326), 3857)
+            AS geom
+        ) p ON v.geom <-> p.geom < 200
+    ORDER BY v.geom <-> p.geom
+    LIMIT 1
+)
+SELECT s_point.start_id, e_point.end_id
+        , s_point.geom AS geom_start
+        , e_point.geom AS geom_end
+    FROM s_point, e_point
+;
+```
+
+
+Route, using the directional approach.
+
+```sql
+SELECT d.*, n.geom AS node_geom, e.geom AS edge_geom
+    FROM pgr_dijkstra(
+        'SELECT e.edge_id AS id
+                , e.vertex_id_source AS source
+                , e.vertex_id_target AS target
+                , e.cost_length_forward AS cost
+                , e.cost_length_reverse AS reverse_cost
+                , e.geom
+            FROM osm.routing_water_edge e
+            ',
+            :start_id, :end_id, directed := True
+        ) d
+    INNER JOIN osm.routing_water_vertex n ON d.node = n.id
+    LEFT JOIN osm.routing_water_edge e ON d.edge = e.edge_id
+;
+```
+
+![Example route using D.C. water layer.](dc-water-route-example.png)
+
+## Challenge: Polygons with Water Routing
+
+Waterway routing using lines only is often complicated by the nature of waterways
+and the way routes flow through steams and rivers (lines) and also through ponds
+and lakes (polygons). The data prepared by the above procedure only provides
+the line-based functionality.
+
+The following image ([source](https://blog.rustprooflabs.com/2022/10/pgrouting-lines-through-polygons))
+visualizes the impact polygons can have on a line-only routing network for water routes.
+
+![Image alternates between showing / hiding water polygons, creating significant gaps in the routing network.](https://blog.rustprooflabs.com/static/images/water-polygons-are-important-for-routing.gif)
+
+
+
+See the [Routing with Lines through Polygons](https://blog.rustprooflabs.com/2022/10/pgrouting-lines-through-polygons)
+blog post to explore one possible approach to solving this problem.
+