Create a user part for H2Network documentation

[gpetit]

In the h2gis.org documentation there is a part dedicated to H2Network. The functions are well documented (see #352) (great job, really) but I was wondering if you could add a user part.

My problem is that if you don't know anything about graph theory, you have real difficulties to understand this documentation. I mean, here we are mainly with a mathematician / informatician point of view (which is, once again, important).

So, because the different pages are quite big enough, maybe we could create a specific sub-part called "H2Network examples" or "H2Network in action" ... in which all the functions will be described in practice (with real small examples) ?

@agouge @ebocher @mlecoeuvre @nicolas-f

[agouge]

Sounds like a good idea :+1:

[mlecoeuvre]

I wrote this example but it's not complete. It can be used for a base of documentation.

CREATE TABLE test(road LINESTRING, GID serial, description VARCHAR,
                  direction int, length double);
INSERT INTO test VALUES
('LINESTRING (0 0, 1 2)', null, 'road1', 1, null),
('LINESTRING (1 2, 2 3, 4 3)', null,'road2', 0, null),
('LINESTRING (4 3, 4 4, 1 4, 1 2)', null,'road3', -1, null),
('LINESTRING (4 3, 5 2)', null,'road4', 0, null);
UPDATE test set length=ST_Length(road);

Create the graphe

SELECT ST_Graph('TEST', 'road', 0.1);
SELECT * FROM TEST_EDGES;
-- Answer:
-- | EDGE_ID | START_NODE | END_NODE |
-- | ------- | ---------- | -------- |
-- |       1 |          1 |        2 |
-- |       2 |          2 |        3 |
-- |       3 |          3 |        2 |
-- |       4 |          3 |        4 |

SELECT * FROM TEST_NODES ;
-- Answer: 
-- | NODE_ID |   THE_GEOM  |
-- | ------- | ----------- |
-- |       1 | POINT (0 0) |
-- |       2 | POINT (1 2) |
-- |       3 | POINT (4 3) |
-- |       4 | POINT (5 2) |

-- Join the test_edges with the input table roads to obtain a 
geometric table
CREATE TABLE TEST_EDGES1 AS SELECT a.*, b.* FROM test AS a, 
   test_edges AS b WHERE a.gid=b.edge_id;
SELECT * FROM TEST_EDGES1;
-- Answer: 
-- | ROAD                            | GID | DESCRIPTION | DIRECTION           | LENGTH             | EDGE_ID | START_NODE | END_NODE |
-- | LINESTRING (0 0, 1 2)           | 1   | road1       | 1                   | 2.23606797749979   | 1       | 1          | 2        |
-- | LINESTRING (1 2, 2 3, 4 3)      | 2   | road2       | 0                    |3.414213562373095 | 2       | 2       | 3          |
-- | LINESTRING (4 3, 4 4, 1 4, 1 2) | 3   | road3       | -1                  | 6.0                | 3       | 3          | 2        |
-- | LINESTRING (4 3, 5 2)           | 4   | road4       | 0                   | 1.4142135623730951 | 4       | 3          | 4        |

Calculate the accessibility

SELECT * FROM ST_Accessibility('TEST_EDGES1', 'directed - 
                               direction', '1, 4');
-- Answer: 
-- | source | closest_dest | distance |
-- | ------ | ------------ | -------- |
-- |      1 |            1 |      0.0 |
-- |      2 |            4 |      2.0 |
-- |      3 |            4 |      1.0 |
-- |      4 |            4 |      0.0 |

SELECT * FROM ST_Accessibility('TEST_EDGES1', 'undirected', 
                               '1, 4');
-- Answer: 
-- | source | closest_dest | distance |
-- | ------ | ------------ | -------- |
-- |      2 |            1 |        1 |
-- |      1 |            1 |        0 |
-- |      3 |            4 |        1 |
-- |      4 |            4 |        0 |

Using a weight

SELECT * FROM ST_Accessibility('TEST_EDGES1', 'reversed - 
                               direction', 'length', '1, 4');
-- Answer: 
-- | source | closest_dest |      distance      |
-- | ------ | ------------ | ------------------ |
-- |      2 |            1 | 2,23606797749979   |
-- |      1 |            1 | 0                  |
-- |      3 |            4 | 1,4142135623730951 |
-- |      4 |            4 | 0                  |

Using a destination table

CREATE TABLE dest(the_geom POINT, destination int);
INSERT INTO test VALUES('POINT (4 3)', 3);

SELECT * FROM ST_Accessibility('TEST_EDGES1', 'reversed - 
                               direction', 'dest');
-- Answer: 
-- | source | closest_dest | distance |
-- | ------ | ------------ | -------- |
-- |      2 |            3 | 1        |
-- |      1 |           -1 | ∞        |
-- |      3 |            3 | 0        |
-- |      4 |            3 | 1        |

-- Note: When a destination is not accessible ST_Accessibility
-- returns -1 in closest_dest and ∞ in distance.

SELECT * FROM ST_Accessibility('TEST_EDGES1', 'directed - 
                               direction', 'length', 'dest');
-- Answer: 
-- | source | closest_dest |      distance      |
-- | ------ | ------------ | ------------------ |
-- |      1 |            3 | 5,650281539872885  |
-- |      2 |            3 | 3,414213562373095  |
-- |      3 |            3 | 0                  |
-- |      4 |            3 | 1,4142135623730951 |

[agouge]

@gpetit Were you thinking more of an example with real world (e.g., OSM) data?

[gpetit]

Yeah maybe. Anyway we can postpone this issue (few days) because we have other emergencies :-)