h3 3.4.4 → 3.5.0

data/ext/h3/src/src/apps/filters/kRing.c

@@ -17,7 +17,7 @@
  * @brief stdin/stdout filter that converts from integer H3 indexes to
  * k-rings
  *
- *  usage: `kRing -k <k> [--print-distances] [--origin origin]`
+ *  See `kRing --help` for usage.
  *
  *  The program reads H3 indexes from stdin until EOF and outputs
  *  the H3 indexes within k-ring `k` to stdout.
@@ -30,6 +30,7 @@
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include "args.h"
 #include "h3api.h"
 #include "utility.h"
 
@@ -58,8 +59,7 @@ int main(int argc, char* argv[]) {
     int k = 0;
     H3Index origin = 0;
 
-    Arg helpArg = {.names = {"-h", "--help"},
-                   .helpText = "Show this help message."};
+    Arg helpArg = ARG_HELP;
     Arg kArg = {.names = {"-k", NULL},
                 .required = true,
                 .scanFormat = "%d",
@@ -75,7 +75,7 @@ int main(int argc, char* argv[]) {
         .valueName = "origin",
         .value = &origin,
         .helpText =
-            "Origin, or not specified to read origins from standard in."};
+            "Origin, or not specified to read origins from standard input."};
 
     Arg* args[] = {&helpArg, &kArg, &printDistancesArg, &originArg};
 

data/ext/h3/src/src/apps/filters/localIjToH3.c

@@ -17,7 +17,7 @@
  * @brief stdin/stdout filter that converts from local IJ coordinates to
  * H3 indexes. This is experimental.
  *
- *  usage: `localIjToH3 [origin]`
+ *  See `localIjToH3 --help` for usage.
  *
  *  The program reads IJ coordinates (in the format `i j` separated by newlines)
  *  from stdin and outputs the corresponding H3 indexes to stdout, until EOF is
@@ -33,6 +33,7 @@
 #include <inttypes.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include "args.h"
 #include "h3api.h"
 #include "utility.h"
 
@@ -46,30 +47,71 @@ void doCell(const CoordIJ *ij, H3Index origin) {
 }
 
 int main(int argc, char *argv[]) {
-    // check command line args
-    if (argc != 2) {
-        fprintf(stderr, "usage: %s [origin]\n", argv[0]);
-        exit(1);
-    }
+    H3Index origin = 0;
+    CoordIJ ij = {0};
 
-    H3Index origin = H3_EXPORT(stringToH3(argv[1]));
-    if (!H3_EXPORT(h3IsValid)(origin)) error("origin is invalid");
+    Arg helpArg = ARG_HELP;
+    Arg originArg = {
+        .names = {"-o", "--origin"},
+        .scanFormat = "%" PRIx64,
+        .valueName = "origin",
+        .value = &origin,
+        .required = true,
+        .helpText =
+            "Origin (anchoring index) for the local coordinate system."};
+    Arg iArg = {.names = {"-i", NULL},
+                .scanFormat = "%d",
+                .valueName = "i",
+                .value = &ij.i,
+                .helpText =
+                    "I coordinate. If not specified \"i j\" pairs will be read "
+                    "from standard input."};
+    Arg jArg = {.names = {"-j", NULL},
+                .scanFormat = "%d",
+                .valueName = "j",
+                .value = &ij.j,
+                .helpText = "J coordinate."};
 
-    // process the coordinates on stdin
-    char buff[BUFF_SIZE];
-    while (1) {
-        // get coordinates from stdin
-        if (!fgets(buff, BUFF_SIZE, stdin)) {
-            if (feof(stdin))
-                break;
-            else
-                error("reading IJ coordinates from stdin");
-        }
+    Arg *args[] = {&helpArg, &originArg, &iArg, &jArg};
+    const int numArgs = 4;
+    const char *helpText = "Converts local IJ coordinates to H3 indexes";
+
+    if (parseArgs(argc, argv, numArgs, args, &helpArg, helpText)) {
+        return helpArg.found ? 0 : 1;
+    }
 
-        CoordIJ ij;
-        if (!sscanf(buff, "%d %d", &ij.i, &ij.j))
-            error("Parsing IJ coordinates. Expected `i j`.");
+    if (!H3_EXPORT(h3IsValid)(origin)) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Origin is invalid.", NULL);
+        return 1;
+    }
 
+    if (iArg.found != jArg.found) {
+        // One is found but the other is not.
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "I and J must both be specified.", NULL);
+        return 1;
+    }
+
+    if (iArg.found) {
         doCell(&ij, origin);
+    } else {
+        // process the coordinates on stdin
+        char buff[BUFF_SIZE];
+        while (1) {
+            // get coordinates from stdin
+            if (!fgets(buff, BUFF_SIZE, stdin)) {
+                if (feof(stdin))
+                    break;
+                else
+                    error("reading IJ coordinates from stdin");
+            }
+
+            if (!sscanf(buff, "%d %d", &ij.i, &ij.j))
+                error(
+                    "Parsing IJ coordinates. Expected `<integer> <integer>`.");
+
+            doCell(&ij, origin);
+        }
     }
 }

data/ext/h3/src/src/apps/miscapps/h3ToGeoBoundaryHier.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Uber Technologies, Inc.
+ * Copyright 2016-2017, 2019 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,7 @@
  * @brief takes an H3 index and generates cell boundaries for all descendants
  * at a specified resolution.
  *
- *  usage: `h3ToGeoBoundaryHier H3Index [resolution outputMode]`
+ *  See `h3ToGeoBoundaryHier` for usage.
  *
  *  The program generates the cell boundaries in lat/lon coordinates for all
  *  hierarchical children of H3Index at the specified resolution. If the
@@ -27,21 +27,23 @@
  *  `resolution` should be a positive integer. The default is 0 (i.e., only the
  *       specified cell H3Index would be processed).
  *
- *  `outputMode` indicates the type of output; currently the choices are 0 for
- *       plain text output (the default) and 1 for KML output.
+ *  `--kml` indicates KML output format; if not specified plain text output is
+ *       the default.
  *
  *  Examples:
  *  ---------
  *
- *     `h3ToGeoBoundaryHier 836e9bfffffffff`
+ *     `h3ToGeoBoundaryHier --parent 836e9bfffffffff`
  *        - outputs the cell boundary in lat/lon for cell `836e9bfffffffff` as
  *          plain text
  *
- *     `h3ToGeoBoundaryHier 820ceffffffffff 4 1 > cells.kml`
+ *     `h3ToGeoBoundaryHier --parent 820ceffffffffff --resolution 4 --kml >
+ *          cells.kml`
  *        - outputs the cell boundaries of all of the resolution 4 descendants
  *          of cell `820ceffffffffff` as a KML file (redirected to `cells.kml`).
  *
- *     `h3ToGeoBoundaryHier 86283082fffffff 9 1 > uber9cells.kml`
+ *     `h3ToGeoBoundaryHier --parent 86283082fffffff --resolution 9 --kml >
+ *          uber9cells.kml`
  *        - creates a KML file containing the cell boundaries of all of the
  *          resolution 9 hexagons covering Uber HQ and the surrounding region of
  *          San Francisco
@@ -51,14 +53,12 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include "args.h"
 #include "baseCells.h"
-#include "coordijk.h"
-#include "geoCoord.h"
 #include "h3Index.h"
 #include "h3api.h"
 #include "kml.h"
 #include "utility.h"
-#include "vec2d.h"
 
 void doCell(H3Index h, int isKmlOut) {
     GeoBoundary b;
@@ -94,55 +94,79 @@ void recursiveH3IndexToGeo(H3Index h, int res, int isKmlOut) {
     }
 }
 
-int main(int argc, char* argv[]) {
-    // check command line args
-    if (argc < 2 || argc > 5) {
-        fprintf(stderr, "usage: %s H3Index [resolution outputMode]\n", argv[0]);
-        exit(1);
+int main(int argc, char *argv[]) {
+    int res;
+    H3Index parentIndex = 0;
+
+    Arg helpArg = ARG_HELP;
+    Arg resArg = {.names = {"-r", "--resolution"},
+                  .scanFormat = "%d",
+                  .valueName = "res",
+                  .value = &res,
+                  .helpText =
+                      "Resolution, if less than the resolution of the parent "
+                      "only the parent is printed. Default the resolution of "
+                      "the parent."};
+    Arg parentArg = {
+        .names = {"-p", "--parent"},
+        .scanFormat = "%" PRIx64,
+        .valueName = "parent",
+        .value = &parentIndex,
+        .required = true,
+        .helpText = "Print cell boundaries descendent from this index."};
+    Arg kmlArg = ARG_KML;
+    DEFINE_KML_NAME_ARG(userKmlName, kmlNameArg);
+    DEFINE_KML_DESC_ARG(userKmlDesc, kmlDescArg);
+
+    Arg *args[] = {&helpArg, &resArg,     &parentArg,
+                   &kmlArg,  &kmlNameArg, &kmlDescArg};
+    const int numArgs = 6;
+    const char *helpText = "Print cell boundaries for descendants of an index";
+
+    if (parseArgs(argc, argv, numArgs, args, &helpArg, helpText)) {
+        return helpArg.found ? 0 : 1;
     }
 
-    H3Index rootCell = H3_EXPORT(stringToH3)(argv[1]);
-    int baseCell = H3_GET_BASE_CELL(rootCell);
-    int rootRes = H3_GET_RESOLUTION(rootCell);
-    if (baseCell < 0 || baseCell >= NUM_BASE_CELLS) {
-        error("invalid base cell number");
+    if (res > MAX_H3_RES) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Resolution exceeds maximum resolution.", NULL);
+        return 1;
     }
 
-    int res = 0;
-    int isKmlOut = 0;
-    if (argc > 2) {
-        if (!sscanf(argv[2], "%d", &res))
-            error("resolution must be an integer");
+    if (!H3_EXPORT(h3IsValid)(parentIndex)) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Parent index is invalid.", NULL);
+        return 1;
+    }
 
-        if (res > MAX_H3_RES)
-            error("specified resolution exceeds max resolution");
+    int rootRes = H3_GET_RESOLUTION(parentIndex);
 
-        if (argc > 3) {
-            if (!sscanf(argv[3], "%d", &isKmlOut))
-                error("outputMode must be an integer");
+    if (kmlArg.found) {
+        char *kmlName;
+        if (kmlNameArg.found) {
+            kmlName = strdup(userKmlName);
+        } else {
+            kmlName = calloc(BUFF_SIZE, sizeof(char));
 
-            if (isKmlOut != 0 && isKmlOut != 1)
-                error("outputMode must be 0 or 1");
+            sprintf(kmlName, "Cell %" PRIx64 " Res %d", parentIndex,
+                    ((res <= rootRes) ? rootRes : res));
+        }
 
-            if (isKmlOut) {
-                char name[BUFF_SIZE];
+        char *kmlDesc = "Generated by h3ToGeoBoundaryHier";
+        if (kmlDescArg.found) kmlDesc = userKmlDesc;
 
-                sprintf(name, "Cell %" PRIx64 " Res %d", rootCell,
-                        ((res <= rootRes) ? rootRes : res));
+        kmlBoundaryHeader(kmlName, kmlDesc);
 
-                kmlBoundaryHeader(name, "cell boundary");
-            }
-        }
+        free(kmlName);
     }
 
     // generate the points
-
     if (res <= rootRes) {
-        doCell(rootCell, isKmlOut);
+        doCell(parentIndex, kmlArg.found);
     } else {
-        H3_SET_RESOLUTION(rootCell, res);
-        recursiveH3IndexToGeo(rootCell, rootRes + 1, isKmlOut);
+        H3_SET_RESOLUTION(parentIndex, res);
+        recursiveH3IndexToGeo(parentIndex, rootRes + 1, kmlArg.found);
     }
 
-    if (isKmlOut) kmlBoundaryFooter();
+    if (kmlArg.found) kmlBoundaryFooter();
 }

data/ext/h3/src/src/apps/miscapps/h3ToGeoHier.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Uber Technologies, Inc.
+ * Copyright 2016-2017, 2019 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,7 @@
  * @brief takes an H3 index and generates cell center points for descendants a
  * specified resolution.
  *
- *  usage: `h3ToGeoHier H3Index [resolution outputMode]`
+ *  See `h3ToGeoHier --help` for usage.
  *
  *  The program generates the cell center points in lat/lon coordinates for all
  *  hierarchical children of H3Index at the specified resolution. If the
@@ -27,22 +27,23 @@
  *  `resolution` should be a positive integer. The default is 0 (i.e., only the
  *       specified cell H3Index would be processed).
  *
- *  `outputMode` indicates the type of output; currently the choices are 0 for
- *       plain text output (the default) and 1 for KML output.
+ *  `--kml` indicates KML output format; if not specified plain text output is
+ *       the default.
  *
  *  Examples:
  *  ---------
  *
- *     `h3ToGeoHier 836e9bfffffffff`
+ *     `h3ToGeoHier --parent 836e9bfffffffff`
  *        - outputs the cell center point in lat/lon for cell
  *          `836e9bfffffffff` as plain text
  *
- *     `h3ToGeoHier 820ceffffffffff 4 1 > pts.kml`
+ *     `h3ToGeoHier --parent 820ceffffffffff --resolution 4 --kml > pts.kml`
  *        - outputs the cell center points of all of the resolution 4
  *          descendants of cell `820ceffffffffff` as a KML file (redirected to
  *          `pts.kml`).
  *
- *     `h3ToGeoHier 86283082fffffff 9 1 > uber9pts.kml`
+ *     `h3ToGeoHier --parent 86283082fffffff --resolution 9 --kml >
+ *          uber9pts.kml`
  *        - creates a KML file containing the cell center points of all of the
  *          resolution 9 hexagons covering Uber HQ and the surrounding region of
  *          San Francisco.
@@ -52,14 +53,12 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include "args.h"
 #include "baseCells.h"
-#include "coordijk.h"
-#include "geoCoord.h"
 #include "h3Index.h"
 #include "h3api.h"
 #include "kml.h"
 #include "utility.h"
-#include "vec2d.h"
 
 void doCell(H3Index h, int isKmlOut) {
     GeoCoord g;
@@ -95,55 +94,81 @@ void recursiveH3IndexToGeo(H3Index h, int res, int isKmlOut) {
     }
 }
 
-int main(int argc, char* argv[]) {
-    // check command line args
-    if (argc < 2 || argc > 5) {
-        fprintf(stderr, "usage: %s H3Index [resolution outputMode]\n", argv[0]);
-        exit(1);
+int main(int argc, char *argv[]) {
+    int res = 0;
+    H3Index parentIndex = 0;
+
+    Arg helpArg = ARG_HELP;
+    Arg resArg = {.names = {"-r", "--resolution"},
+                  .scanFormat = "%d",
+                  .valueName = "res",
+                  .value = &res,
+                  .helpText =
+                      "Resolution, if less than the resolution of the parent "
+                      "only the parent is printed. Default the resolution of "
+                      "the parent."};
+    Arg parentArg = {
+        .names = {"-p", "--parent"},
+        .scanFormat = "%" PRIx64,
+        .valueName = "parent",
+        .value = &parentIndex,
+        .required = true,
+        .helpText = "Print cell centers descendent from this index."};
+    Arg kmlArg = ARG_KML;
+    DEFINE_KML_NAME_ARG(userKmlName, kmlNameArg);
+    DEFINE_KML_DESC_ARG(userKmlDesc, kmlDescArg);
+
+    Arg *args[] = {&helpArg, &resArg,     &parentArg,
+                   &kmlArg,  &kmlNameArg, &kmlDescArg};
+    const int numArgs = 6;
+    const char *helpText =
+        "Print cell center points for descendants of an index";
+
+    if (parseArgs(argc, argv, numArgs, args, &helpArg, helpText)) {
+        return helpArg.found ? 0 : 1;
     }
 
-    H3Index rootCell = H3_EXPORT(stringToH3)(argv[1]);
-    int baseCell = H3_GET_BASE_CELL(rootCell);
-    int rootRes = H3_GET_RESOLUTION(rootCell);
-    if (baseCell < 0 || baseCell >= NUM_BASE_CELLS) {
-        error("invalid base cell number");
+    if (res > MAX_H3_RES) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Resolution exceeds maximum resolution.", NULL);
+        return 1;
     }
 
-    int res = 0;
-    int isKmlOut = 0;
-    if (argc > 2) {
-        if (!sscanf(argv[2], "%d", &res))
-            error("resolution must be an integer");
+    if (!H3_EXPORT(h3IsValid)(parentIndex)) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Parent index is invalid.", NULL);
+        return 1;
+    }
 
-        if (res > MAX_H3_RES)
-            error("specified resolution exceeds max resolution");
+    int rootRes = H3_GET_RESOLUTION(parentIndex);
 
-        if (argc > 3) {
-            if (!sscanf(argv[3], "%d", &isKmlOut))
-                error("outputMode must be an integer");
+    if (kmlArg.found) {
+        char *kmlName;
+        if (kmlNameArg.found) {
+            kmlName = strdup(userKmlName);
+        } else {
+            kmlName = calloc(BUFF_SIZE, sizeof(char));
 
-            if (isKmlOut != 0 && isKmlOut != 1)
-                error("outputMode must be 0 or 1");
+            sprintf(kmlName, "Cell %" PRIx64 " Res %d", parentIndex,
+                    ((res <= rootRes) ? rootRes : res));
+        }
 
-            if (isKmlOut) {
-                char name[BUFF_SIZE];
+        char *kmlDesc = "Generated by h3ToGeoHier";
+        if (kmlDescArg.found) kmlDesc = userKmlDesc;
 
-                sprintf(name, "Cell %" PRIx64 " Res %d", rootCell,
-                        ((res <= rootRes) ? rootRes : res));
+        kmlBoundaryHeader(kmlName, kmlDesc);
 
-                kmlBoundaryHeader(name, "cell center");
-            }
-        }
+        free(kmlName);
     }
 
     // generate the points
 
     if (res <= rootRes) {
-        doCell(rootCell, isKmlOut);
+        doCell(parentIndex, kmlArg.found);
     } else {
-        H3_SET_RESOLUTION(rootCell, res);
-        recursiveH3IndexToGeo(rootCell, rootRes + 1, isKmlOut);
+        H3_SET_RESOLUTION(parentIndex, res);
+        recursiveH3IndexToGeo(parentIndex, rootRes + 1, kmlArg.found);
     }
 
-    if (isKmlOut) kmlBoundaryFooter();
+    if (kmlArg.found) kmlBoundaryFooter();
 }