Beautified mapcode.c for publishing

Author: rijnb

mapcode.c

@@ -3,19 +3,56 @@
  * For terms of use refer to http://www.mapcode.com/downloads.html
  */
 
+/**
+ * This application uses the Mapcode C library to encode and decode Mapcodes.
+ * It also serves as an example of how to use this library in a C environment.
+ *
+ * It also offers additional options to generate "test sets" of coordinates
+ * and Mapcodes to check other Mapcode implementations against reference data.
+ *
+ * These test sets consist of:
+ *
+ * - a number of "grid distributed" coordinates, which forms a set of coordinates
+ *   and their Mapcodes, wrapped as a grid around the Earth;
+ *
+ * - a number of "random uniformly distributed" coordinates, which forms a set of
+ *   random coordiantes on the surface of Earth; or
+ *
+ * - a set which consists of typical Mapcode "boundaries" and "edge cases", based
+ *   on the internal implementation of the boundaries database of the Mapcode
+ *   implementation.
+ */
+
 #include <stdio.h>
 #include <math.h>
 #include "mapcoder/mapcoder.c"
 
-static const double PI = 3.14159265358979323846;
-static const int RESULTS_MAX = 64;
-static const int SHOW_PROGRESS = 125;
 
-static int largestNrOfResults = 0;
-static double latLargestNrOfResults = 0.0;
-static double lonLargestNrOfResults = 0.0;
-static int totalNrOfResults = 0;
 
+/**
+ * Some global constants to be used.
+ */
+static const double PI              = 3.14159265358979323846;
+static const int    RESULTS_MAX     = 64;
+static const int    SHOW_PROGRESS   = 125;
+
+
+
+/**
+ * These statistics are stored globally so they can be updated easily by the
+ * generateAndOutputMapcodes() method.
+ */
+static int      largestNrOfResults      = 0;
+static double   latLargestNrOfResults   = 0.0;
+static double   lonLargestNrOfResults   = 0.0;
+static int      totalNrOfResults        = 0;
+
+
+
+/**
+ * The usage() method explains how this application can be used. It is called
+ * whenever a incorrect amount or combination of parameters is entered.
+ */
 static void usage(const char* appName) {
     printf("MAPCODE (C library version %s)\n", mapcode_cversion);
     printf("Copyright (C) 2014 Stichting Mapcode Foundation\n");
@@ -48,20 +85,35 @@ static void usage(const char* appName) {
     printf("           lat-deg, lon-deg  : [-90..90], [-180..180]\n");
     printf("           x, y, z           : [-1..1]\n");
     printf("\n");
-    printf("\n     stdout: used for outputting 3D point data; stderr: used for statistics.");
-    printf("\n");
     printf("       The lat/lon pairs will be distributed over the 3D surface of the Earth\n");
     printf("       and the (x, y, z) coordinates are placed on a sphere with radius 1.\n");
+    printf("       The (x, y, z) coordinates are primarily meant for visualization of the data set.\n");
+    printf("\n");
+    printf("\n     Notes on the use of stdout and stderr:\n");
+    printf("\n     stdout: used for outputting 3D point data; stderr: used for statistics.");
+    printf("\n     You can redirect stdout to a destination file, while stderr will show progress.\n");
 }
 
+
+
+/**
+ * The method radToDeg() converts radians to degrees.
+ */
 static double radToDeg(double rad){
     return (rad / PI) * 180.0;
 }
 
+
+
+/**
+ * The method degToRad() converts degrees to radians.
+ */
 static double degToRad(double deg){
     return (deg / 180.0) * PI;
 }
 
+
+
 /**
  * Given a single number between 0..1, generate a latitude, longitude (in degrees) and a 3D
  * (x, y, z) point on a sphere with a radius of 1.
@@ -87,6 +139,12 @@ static void unitToLatLonDeg(
     *lonDeg = isnan(lonRad) ? 180.0 : radToDeg(lonRad);
 }
 
+
+
+/**
+ * The method convertLatLonToXYZ() convertes a lat/lon pair to a (x, y, z) coordinate
+ * on a sphere with radius 1.
+ */
 static void convertLatLonToXYZ(double latDeg, double lonDeg, double* x, double* y, double* z) {
     double latRad = degToRad(latDeg);
     double lonRad = degToRad(lonDeg);
@@ -95,7 +153,14 @@ static void convertLatLonToXYZ(double latDeg, double lonDeg, double* x, double*
     *z = sin(latRad);
 }
 
-static int printMapcodes(double lat, double lon, int iShowError) {
+
+
+/**
+ * The method printMapcode() generates and outputs Mapcodes for a lat/lon pair.
+ * If iShowError != 0, then encoding errors are output to stderr, otherwise they
+ * are ignored.
+ */
+static int generateAndOutputMapcodes(double lat, double lon, int iShowError) {
     const char* results[RESULTS_MAX];
     int context = 0;
     const int nrResults = coord2mc(results, lat, lon, context);
@@ -124,6 +189,12 @@ static int printMapcodes(double lat, double lon, int iShowError) {
     return nrResults;
 }
 
+
+
+/**
+ * This is the main() method which is called from the command-line.
+ * Return code 0 means success. Any other values means some sort of error occurred.
+ */
 int main(const int argc, const char** argv)
 {
     // Provide usage message if no arguments specified.
@@ -228,47 +299,50 @@ int main(const int argc, const char** argv)
             lon = (maxLon - minLon ) / 2.0;
 
             // Try center.
-            printMapcodes(lat, lon, 0);
+            generateAndOutputMapcodes(lat, lon, 0);
 
             // Try corners.
-            printMapcodes(minLat, minLon, 0);
-            printMapcodes(minLat, maxLon, 0);
-            printMapcodes(maxLat, minLon, 0);
-            printMapcodes(maxLat, maxLon, 0);
+            generateAndOutputMapcodes(minLat, minLon, 0);
+            generateAndOutputMapcodes(minLat, maxLon, 0);
+            generateAndOutputMapcodes(maxLat, minLon, 0);
+            generateAndOutputMapcodes(maxLat, maxLon, 0);
 
             // Try JUST inside.
             double factor = 1.0;
             for (int j = 1; j < 6; ++j) {
 
                 double d = 1.0 / factor;
-                printMapcodes(minLat + d, minLon + d, 0);
-                printMapcodes(minLat + d, maxLon - d, 0);
-                printMapcodes(maxLat - d, minLon + d, 0);
-                printMapcodes(maxLat - d, maxLon - d, 0);
+                generateAndOutputMapcodes(minLat + d, minLon + d, 0);
+                generateAndOutputMapcodes(minLat + d, maxLon - d, 0);
+                generateAndOutputMapcodes(maxLat - d, minLon + d, 0);
+                generateAndOutputMapcodes(maxLat - d, maxLon - d, 0);
 
                 // Try JUST outside.
-                printMapcodes(minLat - d, minLon - d, 0);
-                printMapcodes(minLat - d, maxLon + d, 0);
-                printMapcodes(maxLat + d, minLon - d, 0);
-                printMapcodes(maxLat + d, maxLon + d, 0);
+                generateAndOutputMapcodes(minLat - d, minLon - d, 0);
+                generateAndOutputMapcodes(minLat - d, maxLon + d, 0);
+                generateAndOutputMapcodes(maxLat + d, minLon - d, 0);
+                generateAndOutputMapcodes(maxLat + d, maxLon + d, 0);
                 factor = factor * 10.0;
             }
 
             // Try 22m outside.
-            printMapcodes(minLat - 22, (maxLon - minLon) / 2, 0);
-            printMapcodes(minLat - 22, (maxLon - minLon) / 2, 0);
-            printMapcodes(maxLat + 22, (maxLon - minLon) / 2, 0);
-            printMapcodes(maxLat + 22, (maxLon - minLon) / 2, 0);
+            generateAndOutputMapcodes(minLat - 22, (maxLon - minLon) / 2, 0);
+            generateAndOutputMapcodes(minLat - 22, (maxLon - minLon) / 2, 0);
+            generateAndOutputMapcodes(maxLat + 22, (maxLon - minLon) / 2, 0);
+            generateAndOutputMapcodes(maxLat + 22, (maxLon - minLon) / 2, 0);
 
             if ((i % SHOW_PROGRESS) == 0) {
-                fprintf(stderr, "Processed %d of %d regions (generated %d Mapcodes)...\r", i, nrPoints, totalNrOfResults);
+                fprintf(stderr, "[%d%%] Processed %d of %d regions (generated %d Mapcodes)...\r",
+                    (int) (((float) i / ((float) nrPoints)) + 0.5),
+                    i, nrPoints, totalNrOfResults);
             }
         }
         fprintf(stderr, "\nStatistics:\n");
         fprintf(stderr, "Total number of 3D points generated     = %d\n", nrPoints);
         fprintf(stderr, "Total number of Mapcodes generated      = %d\n", totalNrOfResults);
         fprintf(stderr, "Average number of Mapcodes per 3D point = %f\n", ((float) totalNrOfResults) / ((float) nrPoints));
-        fprintf(stderr, "Largest number of results for 1 Mapcode = %d at (%f, %f)\n", largestNrOfResults, latLargestNrOfResults, lonLargestNrOfResults);
+        fprintf(stderr, "Largest number of results for 1 Mapcode = %d at (%f, %f)\n",
+            largestNrOfResults, latLargestNrOfResults, lonLargestNrOfResults);
     }
     else if ((strcmp(cmd, "-g") == 0) || (strcmp(cmd, "--grid") == 0) ||
         (strcmp(cmd, "-r") == 0) || (strcmp(cmd, "--random") == 0)) {
@@ -339,22 +413,25 @@ int main(const int argc, const char** argv)
             }
 
             unitToLatLonDeg(unit1, unit2, &lat, &lon);
-            const int nrResults = printMapcodes(lat, lon, 1);
+            const int nrResults = generateAndOutputMapcodes(lat, lon, 1);
             if (nrResults > largestNrOfResults) {
                 largestNrOfResults = nrResults;
                 latLargestNrOfResults = lat;
                 lonLargestNrOfResults = lon;
             }
             totalNrOfResults += nrResults;
             if ((i % SHOW_PROGRESS) == 0) {
-                fprintf(stderr, "Created %d of %d 3D %s data points (generated %d Mapcodes)...\r", i, nrPoints, random ? "random" : "grid", totalNrOfResults);
+                fprintf(stderr, "[%d%%] Created %d of %d 3D %s data points (generated %d Mapcodes)...\r",
+                    (int) (((float) i / ((float) nrPoints)) + 0.5),
+                    i, nrPoints, random ? "random" : "grid", totalNrOfResults);
             }
         }
         fprintf(stderr, "\nStatistics:\n");
         fprintf(stderr, "Total number of 3D points generated     = %d\n", nrPoints);
         fprintf(stderr, "Total number of Mapcodes generated      = %d\n", totalNrOfResults);
         fprintf(stderr, "Average number of Mapcodes per 3D point = %f\n", ((float) totalNrOfResults) / ((float) nrPoints));
-        fprintf(stderr, "Largest number of results for 1 Mapcode = %d at (%f, %f)\n", largestNrOfResults, latLargestNrOfResults, lonLargestNrOfResults);
+        fprintf(stderr, "Largest number of results for 1 Mapcode = %d at (%f, %f)\n",
+            largestNrOfResults, latLargestNrOfResults, lonLargestNrOfResults);
     }
     else {