Update the documentation.

Describe the example appliation and add screenshot of the resulting road network created by the library.
vahancho · Dec 5, 2023 · 4f93782 · 4f93782
1 parent 4ac3342
commit 4f93782
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -4,9 +4,12 @@
 creation of graphs of any types of nodes both directed and undirected with
 the custom weight function.
 
-[![Latest release](https://img.shields.io/github/v/release/vahancho/graphene?include_prereleases)](https://github.com/vahancho/graphene/releases)
-[![Build and test (CMake)](https://github.com/vahancho/graphene/actions/workflows/cmake.yml/badge.svg)](https://github.com/vahancho/graphene/actions/workflows/cmake.yml)
-[![Code coverage](https://codecov.io/gh/vahancho/graphene/graph/badge.svg?token=YLMFIEZBGG)](https://codecov.io/gh/vahancho/graphene)
+[![Latest release](https://img.shields.io/github/v/release/vahancho/graphene?include_prereleases)]
+(https://github.com/vahancho/graphene/releases)
+[![Build and test (CMake)](https://github.com/vahancho/graphene/actions/workflows/cmake.yml/badge.svg)]
+(https://github.com/vahancho/graphene/actions/workflows/cmake.yml)
+[![Code coverage](https://codecov.io/gh/vahancho/graphene/graph/badge.svg?token=YLMFIEZBGG)]
+(https://codecov.io/gh/vahancho/graphene)
 
 ## Prerequisites
 
@@ -27,6 +30,8 @@ not only the shortest path, but the path that corresponds to the minimal overall
 ## API and usage
 
 ```cpp
+#include "graphene.h"
+
 // Declare a graph with nodes as integer values
 Graphene<int> graph;
 
@@ -41,6 +46,7 @@ graph.addEdge(1, 2);
 Calculate the shortest path between two nodes
 
 ```cpp
+#include "graphene.h"
 
 // 1--2--5--8
 //  \     \/
@@ -63,11 +69,22 @@ graph.addEdge(6, 7);
 
 path = graph.shortestPath(1, 6, weightFunction);
 // path = {1, 2, 5, 6}
-
 ```
 
 ## Example (California road network)
 
+The `roadmap` example demonstrates how to use `Graphene` library to create a road
+map. As an input we used the [California Road Network]
+(https://users.cs.utah.edu/~lifeifei/SpatialDataset.htm) which represented by two files:
+`/examples/data/nodes_lon_lat.txt` with the nodes' geodetic coordinates and
+`/examples/data/edges.txt` file with nodes indexes and distance between them.
+Using this data we created an undirected graph and use `Graphene::shortestPaths()`
+function to find all paths that connect a node with all others. The tool exports
+the results as a [KML](https://en.wikipedia.org/wiki/Keyhole_Markup_Language) file
+which can be loaded, for example, into Google Earth application for visualization.
+
+<img src="./examples/data/california_roadmap.png" alt="California Road Network" width="350">
+
 # See also
 
 [California Road Network](https://users.cs.utah.edu/~lifeifei/SpatialDataset.htm)
diff --git a/examples/data/california_roadmap.png b/examples/data/california_roadmap.png
diff --git a/examples/data/nodes_long_lat.txt → examples/data/nodes_lon_lat.txt b/examples/data/nodes_long_lat.txt → examples/data/nodes_lon_lat.txt
diff --git a/examples/main.cpp b/examples/main.cpp
@@ -34,7 +34,7 @@ static const constexpr char usage[] =
 "    edges      path to the file with edges\n"
 "    nodes      path to the file with nodes' coordinates\n"
 "    maxpaths   the maximum number of paths to export\n"
-"    output     the path to the output file.\n";
+"    output     the path to the output KML file.\n";
 
 int main(int argc, char **argv)
 {