working on #2

.Rbuildignore

@@ -1,3 +1,4 @@
+^LICENSE\.md$
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^\.travis\.yml$

.travis.yml

@@ -21,7 +21,3 @@ after_success:
 notifications:
   email:
     - bob@rud.is
-  irc:
-    channels:
-      - "104.236.112.222#builds"
-    nick: travisci

DESCRIPTION

@@ -1,21 +1,28 @@
 Package: mgrs
 Type: Package
-Title: Convert 'MGRS' ('Military Grid Reference System') Coordinates To and From Other Coordinate Systems
-Version: 0.1.0
-Date: 2017-04-09
+Title: Convert 'MGRS' ('Military Grid Reference System') Coordinates From/To Other Coordinate Systems
+Version: 0.2.0
+Date: 2019-02-01
 Author: Bob Rudis (bob@rud.is), Howard Butler
 Maintainer: Bob Rudis <bob@rud.is>
-Description: Convert 'MGRS' ('Military Grid Reference System') coordinates to and from 
-    other coordinate systems.
-URL: https://github.com/hrbrmstr/mgrs
-BugReports: https://github.com/hrbrmstr/mgrs/issues
-License: AGPL
+Description: The 'Military Grid Reference System' ('MGRS') is the geocoordinate
+    standard used by 'NATO' militaries for locating points on the earth. The 'MGRS' 
+    is derived from the 'Universal Transverse Mercator' ('UTM') grid system and 
+    the universal polar stereographic ('UPS') grid system, but uses a different 
+    labeling convention. The 'MGRS' is used for the entire earth. Methods are
+    provided to onvert 'MGRS' coordinates to and from other coordinate systems.
+URL: https://gitlab.com/hrbrmstr/mgrs
+BugReports: https://gitlab.com/hrbrmstr/mgrs/issues
+Encoding: UTF-8
+Copyright: file inst/COPYRIGHTS
+License: MIT + file LICENSE
 Suggests:
     testthat,
     covr
 Depends:
     R (>= 3.2.0)
 Imports:
-    Rcpp
+    Rcpp,
+    magrittr
 LinkingTo: Rcpp
-RoxygenNote: 6.0.1
+RoxygenNote: 6.1.1

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2019
+COPYRIGHT HOLDER: Bob Rudis

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2019 Bob Rudis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export("%>%")
 export(latlng_to_mgrs)
 export(mgrs_precision)
 export(mgrs_to_latlng)
@@ -10,4 +11,5 @@ export(ups_to_mgrs)
 export(utm_to_latlng)
 export(utm_to_mgrs)
 importFrom(Rcpp,sourceCpp)
+importFrom(magrittr,"%>%")
 useDynLib(mgrs, .registration=TRUE)

NEWS.md

@@ -1,6 +1,12 @@
-0.2.1
+0.2.0
 
-* Added `mgrs_area()`
+* Added `mgrs_area()` (completes #1)
+* Changed to MIT license
+* Added COPYRIGHTS info
+* Modified DESCRIPTION Description
+* Updated package docs to include sample grid
+* Added `include_mgrs_ref` logical parameter to `mgrs_to_latlng()`
+  to support #2
 
 0.1.1
 

R/RcppExports.R

@@ -7,12 +7,14 @@
 #' @note vectorized
 #' @param MGRS an MGRS string
 #' @param degrees convert to degrees? Default: `TRUE`
+#' @param include_mgrs_ref if `TRUE` the data frame returned fill include
+#'        the MGRS reference in a column named `mgrs`. Default: `TRUE`.
 #' @export
 #' @return `data.frame`
 #' @examples
 #' mgrs_to_latlng("15TWG0000049776")
-mgrs_to_latlng <- function(MGRS, degrees = TRUE) {
-    .Call(`_mgrs_mgrs_to_latlng`, MGRS, degrees)
+mgrs_to_latlng <- function(MGRS, degrees = TRUE, include_mgrs_ref = TRUE) {
+    .Call(`_mgrs_mgrs_to_latlng`, MGRS, degrees, include_mgrs_ref)
 }
 
 #' Convert latitude/longitude to MGRS string
@@ -45,13 +47,16 @@ utm_to_mgrs <- function(zone, hemisphere, easting, northing, precision = 5L) {
 #' Convert MGRS to UTM
 #'
 #' @md
-#' @param mgrs_string an MGRS string
+#' @note vectorized
+#' @param mgrs_string acharacter vector of MGRS strings
+#' @param include_mgrs_ref if `TRUE` the data frame returned fill include
+#'        the MGRS reference in a column named `mgrs`. Default: `TRUE`.
 #' @return `data.frame`
 #' @export
 #' @examples
 #' mgrs_to_utm("48PUV7729883034")
-mgrs_to_utm <- function(mgrs_string) {
-    .Call(`_mgrs_mgrs_to_utm`, mgrs_string)
+mgrs_to_utm <- function(mgrs_string, include_mgrs_ref = TRUE) {
+    .Call(`_mgrs_mgrs_to_utm`, mgrs_string, include_mgrs_ref)
 }
 
 #' Convert UPS to MGRS
@@ -70,13 +75,16 @@ ups_to_mgrs <- function(hemisphere, easting, northing, precision = 5L) {
 #' Convert MGRS to UPS
 #'
 #' @md
-#' @param mgrs_string an MGRS string
+#' @note vectorized
+#' @param mgrs_string a character vector of MGRS strings
+#' @param include_mgrs_ref if `TRUE` the data frame returned fill include
+#'        the MGRS reference in a column named `mgrs`. Default: `TRUE`.
 #' @return `data.frame`
 #' @export
 #' @examples
 #' mgrs_to_ups("ZGC2677330125")
-mgrs_to_ups <- function(mgrs_string) {
-    .Call(`_mgrs_mgrs_to_ups`, mgrs_string)
+mgrs_to_ups <- function(mgrs_string, include_mgrs_ref = TRUE) {
+    .Call(`_mgrs_mgrs_to_ups`, mgrs_string, include_mgrs_ref)
 }
 
 #' Convert UPS to Latitude/Longitude

R/mgrs-package.R

@@ -1,5 +1,25 @@
-#' Convert 'MGRS' ('Military Grid Reference System') Coordinates To and From Other Coordinate Systems
+#' Convert 'MGRS' ('Military Grid Reference System') Coordinates From/To Other Coordinate Systems
 #'
+#' The 'Military Grid Reference System' ('MGRS') is the geocoordinate
+#' standard used by 'NATO' militaries for locating points on the earth. The 'MGRS'
+#' is derived from the 'Universal Transverse Mercator' ('UTM') grid system and
+#' the universal polar stereographic ('UPS') grid system, but uses a different
+#' labeling convention. The 'MGRS' is used for the entire earth. Methods are
+#' provided to onvert 'MGRS' coordinates to and from other coordinate systems.
+#'
+#' The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ.
+#'
+#' \if{html}{
+#' \figure{mgrs-grid.png}{options: width="850" alt="Figure: The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ"}
+#' }
+#'
+#' \if{latex}{
+#' \figure{mgrs-grid.png}{options: width=30cm}
+#' }
+#'
+#' [CC-BY-SA 3.0](https://en.wikipedia.org/wiki/Military_Grid_Reference_System#/media/File:MGRSgridOriginSchemeAA.png)
+#'
+#' @md
 #' @name mgrs
 #' @docType package
 #' @author Bob Rudis (bob@@rud.is)

R/utils-pipe.R

@@ -0,0 +1,11 @@
+#' Pipe operator
+#'
+#' See \code{magrittr::\link[magrittr]{\%>\%}} for details.
+#'
+#' @name %>%
+#' @rdname pipe
+#' @keywords internal
+#' @export
+#' @importFrom magrittr %>%
+#' @usage lhs \%>\% rhs
+NULL

README.Rmd

@@ -11,38 +11,46 @@ editor_options:
 
 # mgrs
 
-Convert 'MGRS' (Military Grid Reference System) References To and From Other Coordinate Systems
+Convert 'MGRS' (Military Grid Reference System) References From/To Other Coordinate Systems
 
 ## Description
 
+The 'Military Grid Reference System' ('MGRS') is the geocoordinate
+standard used by 'NATO' militaries for locating points on the earth. The 'MGRS' 
+is derived from the 'Universal Transverse Mercator' ('UTM') grid system and 
+the universal polar stereographic ('UPS') grid system, but uses a different 
+labeling convention. The 'MGRS' is used for the entire earth. Methods are
+provided to onvert 'MGRS' coordinates to and from other coordinate systems.
+
 Essentially, a lightweight R wrapper around bits of <https://svn.osgeo.org/gdal/trunk/gdal/frmts/nitf/>.
 
 Decent reference on MGRS & UTM (Universal Transverse Mercator): <https://www.luomus.fi/en/utm-mgrs-atlas-florae-europaeae>.
 
+The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ.
+
+![The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ.](man/figures/mgrs-grid.png)
+
+[CC-BY-SA 3.0](https://en.wikipedia.org/wiki/Military_Grid_Reference_System#/media/File:MGRSgridOriginSchemeAA.png)
+
 ## What's inside the tin?
 
 The following functions are implemented:
 
 - `latlng_to_mgrs`:	Convert latitude/longitude to MGRS string 
-- `mgrs_to_latlng`:	Convert an MGRS string to latitude/longitude **(now returns a `data.frame`)**
+- `mgrs_to_latlng`:	Convert an MGRS string to latitude/longitude
 - `mgrs_to_ups`:	Convert MGRS to UPS
 - `mgrs_to_utm`:	Convert MGRS to UTM
 - `ups_to_mgrs`:	Convert UPS to MGRS
 - `utm_to_mgrs`:	Convert UTM to MGRS
 - `mgrs_precision`: Return MGRS grid reference precision (in meters)
 
-## TODO
-
-- Find all the folks/projects I need to add in the `DESCRIPTION` for auth/ctb & docs
-- Vectorize ALL THE THINGS
-- <strike>Add in support for the other MGRS conversion thingys</strike>
-- More error checking (basic checking is done)
-- Precision validation
-- More tests (basic testing is done)
-
 ## Installation
 
 ```{r eval=FALSE}
+devtools::install_git("https://git.sr.ht/~hrbrmstr/mgrs")
+# OR
+devtools::install_gitlab("hrbrmstr/mgrs")
+# OR 
 devtools::install_github("hrbrmstr/mgrs")
 ```
 
@@ -54,6 +62,7 @@ options(width=120)
 
 ```{r message=FALSE, warning=FALSE, error=FALSE}
 library(mgrs)
+library(hrbrthemes)
 
 # current verison
 packageVersion("mgrs")
@@ -83,6 +92,27 @@ grefs <- c("4Q", "4QFJ", "4QFJ16", "4QFJ1267", "4QFJ123678",
 mgrs_precision(grefs)
 ```
 
+### Better usage in the tidyverse
+
+```{r}
+data.frame(
+  id = 1:50, 
+  mgrs = c("16SEB20", "09UXQ25", "12SVC48", "15SWU64", "11SKA54", "13SDC58", 
+"18TYM20", "18SWH08", "17RML38", "17SKR77", "09RYR61", "12TTP62", 
+"16TBK93", "16TEK73", "15TVG64", "14SNH75", "16SFG94", "15RWP68", 
+"19TEL05", "18SUJ54", "19TBG89", "16TFN87", "15TUM73", "16SBB31", 
+"15SWC44", "12TXS28", "14TML57", "11SND12", "19TCJ00", "18SWK62", 
+"13SDU11", "18TVN87", "17SQV22", "14TMT13", "17TLE65", "14SPE73", 
+"10TGP36", "18TTL93", "19TCG20", "17SNT42", "14TMQ40", "16SEE44", 
+"14RNV27", "12SVJ72", "18TXQ90", "17SQB46", "11TKN95", "17SNC25", 
+"16TBQ64", "13TCH16"),
+  stringsAsFactors = FALSE
+) -> sample_dta
+
+dplyr::mutate(sample_dta, x = lapply(mgrs, mgrs_to_latlng, include_mgrs_ref = FALSE)) %>% 
+  tidyr::unnest(x)
+```
+
 ### Visual Verification
 
 ```{r fig.retina=2, fig.width=10, fig.height=5}
@@ -103,8 +133,9 @@ c("16SEB20", "09UXQ25", "12SVC48", "15SWU64", "11SKA54", "13SDC58",
 
 mgrs_to_latlng(mgrs_state_centers) %>% 
   ggplot(aes(lng, lat)) +
-  geom_point(shape=22, size=2, color="white", fill="black") +
-  coord_map("polyconic")
+  geom_point(shape=22, size=2, color="black", fill="white") +
+  coord_map("polyconic") +
+  theme_ft_rc(grid="XY")
 ```
 
 ## Code of Conduct

README.md

@@ -12,44 +12,51 @@ verified](https://img.shields.io/badge/keybase-verified-brightgreen.svg)](https:
 
 # mgrs
 
-Convert ‘MGRS’ (Military Grid Reference System) References To and From
-Other Coordinate Systems
+Convert ‘MGRS’ (Military Grid Reference System) References From/To Other
+Coordinate Systems
 
 ## Description
 
+The ‘Military Grid Reference System’ (‘MGRS’) is the geocoordinate
+standard used by ‘NATO’ militaries for locating points on the earth. The
+‘MGRS’ is derived from the ‘Universal Transverse Mercator’ (‘UTM’) grid
+system and the universal polar stereographic (‘UPS’) grid system, but
+uses a different labeling convention. The ‘MGRS’ is used for the entire
+earth. Methods are provided to onvert ‘MGRS’ coordinates to and from
+other coordinate systems.
+
 Essentially, a lightweight R wrapper around bits of
 <https://svn.osgeo.org/gdal/trunk/gdal/frmts/nitf/>.
 
 Decent reference on MGRS & UTM (Universal Transverse Mercator):
 <https://www.luomus.fi/en/utm-mgrs-atlas-florae-europaeae>.
 
+The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ.
+
+![The origin of the MGRS grid, in the Pacific. Honolulu is in
+4QFJ.](man/figures/mgrs-grid.png)
+
+[CC-BY-SA 3.0](https://en.wikipedia.org/wiki/Military_Grid_Reference_System#/media/File:MGRSgridOriginSchemeAA.png)
+
 ## What’s inside the tin?
 
 The following functions are implemented:
 
   - `latlng_to_mgrs`: Convert latitude/longitude to MGRS string
   - `mgrs_to_latlng`: Convert an MGRS string to latitude/longitude
-    **(now returns a `data.frame`)**
   - `mgrs_to_ups`: Convert MGRS to UPS
   - `mgrs_to_utm`: Convert MGRS to UTM
   - `ups_to_mgrs`: Convert UPS to MGRS
   - `utm_to_mgrs`: Convert UTM to MGRS
   - `mgrs_precision`: Return MGRS grid reference precision (in meters)
 
-## TODO
-
-  - Find all the folks/projects I need to add in the `DESCRIPTION` for
-    auth/ctb & docs
-  - Vectorize ALL THE THINGS
-  - <strike>Add in support for the other MGRS conversion
-    thingys</strike>
-  - More error checking (basic checking is done)
-  - Precision validation
-  - More tests (basic testing is done)
-
 ## Installation
 
 ``` r
+devtools::install_git("https://git.sr.ht/~hrbrmstr/mgrs")
+# OR
+devtools::install_gitlab("hrbrmstr/mgrs")
+# OR 
 devtools::install_github("hrbrmstr/mgrs")
 ```
 
@@ -57,12 +64,13 @@ devtools::install_github("hrbrmstr/mgrs")
 
 ``` r
 library(mgrs)
+library(hrbrthemes)
 
 # current verison
 packageVersion("mgrs")
 ```
 
-    ## [1] '0.1.0'
+    ## [1] '0.2.0'
 
 ``` r
 mgrs_to_latlng("33UXP04")
@@ -135,14 +143,89 @@ grefs <- c("4Q", "4QFJ", "4QFJ16", "4QFJ1267", "4QFJ123678",
 mgrs_precision(grefs)
 ```
 
-    ##         grid_ref precision
-    ## 1             4Q        NA
-    ## 2           4QFJ     1e+05
-    ## 3         4QFJ16     1e+04
-    ## 4       4QFJ1267     1e+03
-    ## 5     4QFJ123678     1e+02
-    ## 6   4QFJ12346789     1e+01
-    ## 7 4QFJ1234567890     1e+00
+    ## # A tibble: 7 x 2
+    ##   grid_ref       precision
+    ##   <chr>              <dbl>
+    ## 1 4Q                    NA
+    ## 2 4QFJ              100000
+    ## 3 4QFJ16             10000
+    ## 4 4QFJ1267            1000
+    ## 5 4QFJ123678           100
+    ## 6 4QFJ12346789          10
+    ## 7 4QFJ1234567890         1
+
+### Better usage in the tidyverse
+
+``` r
+data.frame(
+  id = 1:50, 
+  mgrs = c("16SEB20", "09UXQ25", "12SVC48", "15SWU64", "11SKA54", "13SDC58", 
+"18TYM20", "18SWH08", "17RML38", "17SKR77", "09RYR61", "12TTP62", 
+"16TBK93", "16TEK73", "15TVG64", "14SNH75", "16SFG94", "15RWP68", 
+"19TEL05", "18SUJ54", "19TBG89", "16TFN87", "15TUM73", "16SBB31", 
+"15SWC44", "12TXS28", "14TML57", "11SND12", "19TCJ00", "18SWK62", 
+"13SDU11", "18TVN87", "17SQV22", "14TMT13", "17TLE65", "14SPE73", 
+"10TGP36", "18TTL93", "19TCG20", "17SNT42", "14TMQ40", "16SEE44", 
+"14RNV27", "12SVJ72", "18TXQ90", "17SQB46", "11TKN95", "17SNC25", 
+"16TBQ64", "13TCH16"),
+  stringsAsFactors = FALSE
+) -> sample_dta
+
+dplyr::mutate(sample_dta, x = lapply(mgrs, mgrs_to_latlng, include_mgrs_ref = FALSE)) %>% 
+  tidyr::unnest(x)
+```
+
+    ##    id    mgrs      lat        lng
+    ## 1   1 16SEB20 32.53717  -86.78701
+    ## 2   2 09UXQ25 49.19105 -127.35303
+    ## 3   3 12SVC48 34.15921 -111.65093
+    ## 4   4 15SWU64 34.70027  -92.34486
+    ## 5   5 11SKA54 36.47270 -119.79027
+    ## 6   6 13SDC58 38.66717 -105.57474
+    ## 7   7 18TYM20 41.52143  -72.36334
+    ## 8   8 18SWH08 38.66858  -75.00000
+    ## 9   9 17RML38 27.84288  -81.71090
+    ## 10 10 17SKR77 32.24313  -83.44116
+    ## 11 11 09RYR61 31.69589 -126.25687
+    ## 12 12 12TTP62 43.49440 -113.96832
+    ## 13 13 16TBK93 39.99409  -89.45983
+    ## 14 14 16TEK73 40.01730  -86.17974
+    ## 15 15 15TVG64 41.91094  -93.48232
+    ## 16 16 14SNH75 38.39548  -98.19839
+    ## 17 17 16SFG94 37.38730  -84.85379
+    ## 18 18 15RWP68 30.55091  -92.37442
+    ## 19 19 19TEL05 45.60354  -69.00000
+    ## 20 20 18SUJ54 39.19632  -76.73702
+    ## 21 21 19TBG89 42.33117  -71.67024
+    ## 22 22 16TFN87 43.06136  -84.78947
+    ## 23 23 15TUM73 46.31111  -94.68838
+    ## 24 24 16SBB31 32.59461  -89.87671
+    ## 25 25 15SWC44 38.30721  -92.54249
+    ## 26 26 12TXS28 46.76276 -109.42851
+    ## 27 27 14TML57 41.27989  -99.59705
+    ## 28 28 11SND12 39.02899 -116.88447
+    ## 29 29 19TCJ00 43.32625  -71.46678
+    ## 30 30 18SWK62 39.92798  -74.29783
+    ## 31 31 13SDU11 34.42756 -105.97949
+    ## 32 32 18TVN87 43.08245  -75.24570
+    ## 33 33 17SQV22 35.39912  -78.57750
+    ## 34 34 14TMT13 47.21732 -100.18865
+    ## 35 35 17TLE65 40.18872  -82.64462
+    ## 36 36 14SPE73 35.49902  -97.12568
+    ## 37 37 10TGP36 43.85725 -120.13815
+    ## 38 38 18TTL93 40.89416  -77.49288
+    ## 39 39 19TCG20 41.53142  -71.15763
+    ## 40 40 17SNT42 33.61904  -80.56877
+    ## 41 41 14TMQ40 44.25077  -99.75154
+    ## 42 42 16SEE44 35.60294  -86.55839
+    ## 43 43 14RNV27 31.36434  -98.78970
+    ## 44 44 12SVJ72 39.02853 -111.34659
+    ## 45 45 18TXQ90 44.22846  -72.62103
+    ## 46 46 17SQB46 37.55578  -78.28300
+    ## 47 47 11TKN95 47.36969 -119.78156
+    ## 48 48 17SNC25 38.39800  -80.77096
+    ## 49 49 16TBQ64 44.57333  -90.02272
+    ## 50 50 13TCH16 42.96895 -107.32983
 
 ### Visual Verification
 
@@ -164,11 +247,12 @@ c("16SEB20", "09UXQ25", "12SVC48", "15SWU64", "11SKA54", "13SDC58",
 
 mgrs_to_latlng(mgrs_state_centers) %>% 
   ggplot(aes(lng, lat)) +
-  geom_point(shape=22, size=2, color="white", fill="black") +
-  coord_map("polyconic")
+  geom_point(shape=22, size=2, color="black", fill="white") +
+  coord_map("polyconic") +
+  theme_ft_rc(grid="XY")
 ```
 
-<img src="README_files/figure-gfm/unnamed-chunk-4-1.png" width="960" />
+<img src="README_files/figure-gfm/unnamed-chunk-5-1.png" width="960" />
 
 ## Code of Conduct
 

inst/COPYRIGHTS

@@ -0,0 +1,19 @@
+All R code and src/main.cpp are MIT Licensed.
+
+src/mgrs.[ch], src/tranmerc.[ch], src/ups.[ch] and src/polarst.[ch] are
+sourced from gdal (<https://svn.osgeo.org/gdal/trunk/gdal/frmts/nitf/>) and
+contain the following text which indicates that no licenses apply to these
+components:
+
+/***************************************************************************
+ *
+ * REUSE NOTES
+ *
+ *    MGRS is intended for reuse by any application that does conversions
+ *    between geodetic coordinates and MGRS coordinates.
+ *
+ * LICENSES
+ *
+ *    None apply to this component.
+ *
+ /*

man/mgrs.Rd

@@ -4,9 +4,27 @@
 \name{mgrs}
 \alias{mgrs}
 \alias{mgrs-package}
-\title{Convert 'MGRS' ('Military Grid Reference System') Coordinates To and From Other Coordinate Systems}
+\title{Convert 'MGRS' ('Military Grid Reference System') Coordinates From/To Other Coordinate Systems}
 \description{
-Convert 'MGRS' ('Military Grid Reference System') Coordinates To and From Other Coordinate Systems
+The 'Military Grid Reference System' ('MGRS') is the geocoordinate
+standard used by 'NATO' militaries for locating points on the earth. The 'MGRS'
+is derived from the 'Universal Transverse Mercator' ('UTM') grid system and
+the universal polar stereographic ('UPS') grid system, but uses a different
+labeling convention. The 'MGRS' is used for the entire earth. Methods are
+provided to onvert 'MGRS' coordinates to and from other coordinate systems.
+}
+\details{
+The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ.
+
+\if{html}{
+\figure{mgrs-grid.png}{options: width="850" alt="Figure: The origin of the MGRS grid, in the Pacific. Honolulu is in 4QFJ"}
+}
+
+\if{latex}{
+\figure{mgrs-grid.png}{options: width=30cm}
+}
+
+\href{https://en.wikipedia.org/wiki/Military_Grid_Reference_System#/media/File:MGRSgridOriginSchemeAA.png}{CC-BY-SA 3.0}
 }
 \author{
 Bob Rudis (bob@rud.is)

man/mgrs_to_latlng.Rd

@@ -4,12 +4,15 @@
 \alias{mgrs_to_latlng}
 \title{Convert an MGRS string to latitude/longitude}
 \usage{
-mgrs_to_latlng(MGRS, degrees = TRUE)
+mgrs_to_latlng(MGRS, degrees = TRUE, include_mgrs_ref = TRUE)
 }
 \arguments{
 \item{MGRS}{an MGRS string}
 
 \item{degrees}{convert to degrees? Default: \code{TRUE}}
+
+\item{include_mgrs_ref}{if \code{TRUE} the data frame returned fill include
+the MGRS reference in a column named \code{mgrs}. Default: \code{TRUE}.}
 }
 \value{
 \code{data.frame}

man/mgrs_to_ups.Rd

@@ -4,10 +4,13 @@
 \alias{mgrs_to_ups}
 \title{Convert MGRS to UPS}
 \usage{
-mgrs_to_ups(mgrs_string)
+mgrs_to_ups(mgrs_string, include_mgrs_ref = TRUE)
 }
 \arguments{
-\item{mgrs_string}{an MGRS string}
+\item{mgrs_string}{a character vector of MGRS strings}
+
+\item{include_mgrs_ref}{if \code{TRUE} the data frame returned fill include
+the MGRS reference in a column named \code{mgrs}. Default: \code{TRUE}.}
 }
 \value{
 \code{data.frame}
@@ -15,6 +18,9 @@ mgrs_to_ups(mgrs_string)
 \description{
 Convert MGRS to UPS
 }
+\note{
+vectorized
+}
 \examples{
 mgrs_to_ups("ZGC2677330125")
 }

man/mgrs_to_utm.Rd

@@ -4,10 +4,13 @@
 \alias{mgrs_to_utm}
 \title{Convert MGRS to UTM}
 \usage{
-mgrs_to_utm(mgrs_string)
+mgrs_to_utm(mgrs_string, include_mgrs_ref = TRUE)
 }
 \arguments{
-\item{mgrs_string}{an MGRS string}
+\item{mgrs_string}{acharacter vector of MGRS strings}
+
+\item{include_mgrs_ref}{if \code{TRUE} the data frame returned fill include
+the MGRS reference in a column named \code{mgrs}. Default: \code{TRUE}.}
 }
 \value{
 \code{data.frame}
@@ -15,6 +18,9 @@ mgrs_to_utm(mgrs_string)
 \description{
 Convert MGRS to UTM
 }
+\note{
+vectorized
+}
 \examples{
 mgrs_to_utm("48PUV7729883034")
 }

man/pipe.Rd

@@ -0,0 +1,12 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils-pipe.R
+\name{\%>\%}
+\alias{\%>\%}
+\title{Pipe operator}
+\usage{
+lhs \%>\% rhs
+}
+\description{
+See \code{magrittr::\link[magrittr]{\%>\%}} for details.
+}
+\keyword{internal}

src/RcppExports.cpp

@@ -6,14 +6,15 @@
 using namespace Rcpp;
 
 // mgrs_to_latlng
-DataFrame mgrs_to_latlng(std::vector < std::string > MGRS, bool degrees);
-RcppExport SEXP _mgrs_mgrs_to_latlng(SEXP MGRSSEXP, SEXP degreesSEXP) {
+DataFrame mgrs_to_latlng(std::vector < std::string > MGRS, bool degrees, bool include_mgrs_ref);
+RcppExport SEXP _mgrs_mgrs_to_latlng(SEXP MGRSSEXP, SEXP degreesSEXP, SEXP include_mgrs_refSEXP) {
 BEGIN_RCPP
     Rcpp::RObject rcpp_result_gen;
     Rcpp::RNGScope rcpp_rngScope_gen;
     Rcpp::traits::input_parameter< std::vector < std::string > >::type MGRS(MGRSSEXP);
     Rcpp::traits::input_parameter< bool >::type degrees(degreesSEXP);
-    rcpp_result_gen = Rcpp::wrap(mgrs_to_latlng(MGRS, degrees));
+    Rcpp::traits::input_parameter< bool >::type include_mgrs_ref(include_mgrs_refSEXP);
+    rcpp_result_gen = Rcpp::wrap(mgrs_to_latlng(MGRS, degrees, include_mgrs_ref));
     return rcpp_result_gen;
 END_RCPP
 }
@@ -47,13 +48,14 @@ BEGIN_RCPP
 END_RCPP
 }
 // mgrs_to_utm
-DataFrame mgrs_to_utm(std::string mgrs_string);
-RcppExport SEXP _mgrs_mgrs_to_utm(SEXP mgrs_stringSEXP) {
+DataFrame mgrs_to_utm(std::vector < std::string > mgrs_string, bool include_mgrs_ref);
+RcppExport SEXP _mgrs_mgrs_to_utm(SEXP mgrs_stringSEXP, SEXP include_mgrs_refSEXP) {
 BEGIN_RCPP
     Rcpp::RObject rcpp_result_gen;
     Rcpp::RNGScope rcpp_rngScope_gen;
-    Rcpp::traits::input_parameter< std::string >::type mgrs_string(mgrs_stringSEXP);
-    rcpp_result_gen = Rcpp::wrap(mgrs_to_utm(mgrs_string));
+    Rcpp::traits::input_parameter< std::vector < std::string > >::type mgrs_string(mgrs_stringSEXP);
+    Rcpp::traits::input_parameter< bool >::type include_mgrs_ref(include_mgrs_refSEXP);
+    rcpp_result_gen = Rcpp::wrap(mgrs_to_utm(mgrs_string, include_mgrs_ref));
     return rcpp_result_gen;
 END_RCPP
 }
@@ -72,13 +74,14 @@ BEGIN_RCPP
 END_RCPP
 }
 // mgrs_to_ups
-DataFrame mgrs_to_ups(std::string mgrs_string);
-RcppExport SEXP _mgrs_mgrs_to_ups(SEXP mgrs_stringSEXP) {
+DataFrame mgrs_to_ups(std::vector < std::string > mgrs_string, bool include_mgrs_ref);
+RcppExport SEXP _mgrs_mgrs_to_ups(SEXP mgrs_stringSEXP, SEXP include_mgrs_refSEXP) {
 BEGIN_RCPP
     Rcpp::RObject rcpp_result_gen;
     Rcpp::RNGScope rcpp_rngScope_gen;
-    Rcpp::traits::input_parameter< std::string >::type mgrs_string(mgrs_stringSEXP);
-    rcpp_result_gen = Rcpp::wrap(mgrs_to_ups(mgrs_string));
+    Rcpp::traits::input_parameter< std::vector < std::string > >::type mgrs_string(mgrs_stringSEXP);
+    Rcpp::traits::input_parameter< bool >::type include_mgrs_ref(include_mgrs_refSEXP);
+    rcpp_result_gen = Rcpp::wrap(mgrs_to_ups(mgrs_string, include_mgrs_ref));
     return rcpp_result_gen;
 END_RCPP
 }
@@ -113,12 +116,12 @@ END_RCPP
 }
 
 static const R_CallMethodDef CallEntries[] = {
-    {"_mgrs_mgrs_to_latlng", (DL_FUNC) &_mgrs_mgrs_to_latlng, 2},
+    {"_mgrs_mgrs_to_latlng", (DL_FUNC) &_mgrs_mgrs_to_latlng, 3},
     {"_mgrs_latlng_to_mgrs", (DL_FUNC) &_mgrs_latlng_to_mgrs, 4},
     {"_mgrs_utm_to_mgrs", (DL_FUNC) &_mgrs_utm_to_mgrs, 5},
-    {"_mgrs_mgrs_to_utm", (DL_FUNC) &_mgrs_mgrs_to_utm, 1},
+    {"_mgrs_mgrs_to_utm", (DL_FUNC) &_mgrs_mgrs_to_utm, 2},
     {"_mgrs_ups_to_mgrs", (DL_FUNC) &_mgrs_ups_to_mgrs, 4},
-    {"_mgrs_mgrs_to_ups", (DL_FUNC) &_mgrs_mgrs_to_ups, 1},
+    {"_mgrs_mgrs_to_ups", (DL_FUNC) &_mgrs_mgrs_to_ups, 2},
     {"_mgrs_ups_to_latlng", (DL_FUNC) &_mgrs_ups_to_latlng, 4},
     {"_mgrs_utm_to_latlng", (DL_FUNC) &_mgrs_utm_to_latlng, 5},
     {NULL, NULL, 0}

src/main.cpp

@@ -12,12 +12,15 @@ using namespace Rcpp;
 //' @note vectorized
 //' @param MGRS an MGRS string
 //' @param degrees convert to degrees? Default: `TRUE`
+//' @param include_mgrs_ref if `TRUE` the data frame returned fill include
+//'        the MGRS reference in a column named `mgrs`. Default: `TRUE`.
 //' @export
 //' @return `data.frame`
 //' @examples
 //' mgrs_to_latlng("15TWG0000049776")
 // [[Rcpp::export]]
-DataFrame mgrs_to_latlng(std::vector < std::string > MGRS, bool degrees = true) {
+DataFrame mgrs_to_latlng(std::vector < std::string > MGRS, bool degrees = true,
+                         bool include_mgrs_ref = true) {
 
   double lat, lng;
   long ret, err_ct = 0;
@@ -45,10 +48,24 @@ DataFrame mgrs_to_latlng(std::vector < std::string > MGRS, bool degrees = true)
     Rcpp::warning("One or more errors encounterd while converting %d MGRS input strings");
   }
 
-  return(DataFrame::create(_["mgrs"] = MGRS,
-                           _["lat"] = lat_vec,
-                           _["lng"] = lng_vec,
-                           _["stringsAsFactors"] = false));
+  if (include_mgrs_ref) {
+    return(
+      DataFrame::create(
+        _["mgrs"] = MGRS,
+        _["lat"] = lat_vec,
+        _["lng"] = lng_vec,
+        _["stringsAsFactors"] = false
+      )
+    );
+  } else {
+    return(
+      DataFrame::create(
+        _["lat"] = lat_vec,
+        _["lng"] = lng_vec,
+        _["stringsAsFactors"] = false
+      )
+    );
+  }
 
 }
 
@@ -117,38 +134,69 @@ String utm_to_mgrs(long zone, std::string hemisphere,
 //' Convert MGRS to UTM
 //'
 //' @md
-//' @param mgrs_string an MGRS string
+//' @note vectorized
+//' @param mgrs_string acharacter vector of MGRS strings
+//' @param include_mgrs_ref if `TRUE` the data frame returned fill include
+//'        the MGRS reference in a column named `mgrs`. Default: `TRUE`.
 //' @return `data.frame`
 //' @export
 //' @examples
 //' mgrs_to_utm("48PUV7729883034")
 // [[Rcpp::export]]
-DataFrame mgrs_to_utm(std::string mgrs_string) {
+DataFrame mgrs_to_utm(std::vector < std::string > mgrs_string, bool include_mgrs_ref = true) {
 
   long zone;
   char h_buf[80];
   double easting, northing;
   long ret;
+  IntegerVector zonev = IntegerVector(mgrs_string.size());
+  StringVector hemispherev = StringVector(mgrs_string.size());
+  NumericVector eastingv = NumericVector(mgrs_string.size());
+  NumericVector northingv = NumericVector(mgrs_string.size());
 
-  ret = Convert_MGRS_To_UTM((char *)mgrs_string.c_str(), &zone, h_buf, &easting, &northing);
+  for (unsigned int i=0; i<mgrs_string.size(); i++) {
 
-  if (ret != MGRS_NO_ERROR) {
-    Rcpp::warning("Error converting MGRS to UGM");
-    return(DataFrame::create(_["mgrs"] = mgrs_string,
-                             _["zone"] = NA_INTEGER,
-                             _["hemisphere"] = NA_STRING,
-                             _["easting"] = NA_REAL,
-                             _["northing"] = NA_REAL,
-                             _["stringsAsFactors"] = false));
+    ret = Convert_MGRS_To_UTM((char *)mgrs_string[i].c_str(), &zone, h_buf, &easting, &northing);
+
+    if (ret != MGRS_NO_ERROR) {
+      Rcpp::warning("Error converting MGRS to UGM");
+      zonev[i] = NA_INTEGER;
+      hemispherev[i] = NA_STRING;
+      eastingv[i] = NA_REAL;
+      northingv[i] = NA_REAL;
+    } else {
+      h_buf[1] = '\0';
+      zonev[i] = zone;
+      hemispherev[i] = std::string(h_buf);
+      eastingv[i] = easting;
+      northingv[i] = northing;
+    }
+
+  }
+
+  if (include_mgrs_ref) {
+    return(
+      DataFrame::create(
+        _["mgrs"] = mgrs_string,
+        _["zone"] = zonev,
+        _["hemisphere"] = hemispherev,
+        _["easting"] = eastingv,
+        _["northing"] = northingv,
+        _["stringsAsFactors"] = false
+      )
+    );
   } else {
-    h_buf[1] = '\0';
-    return(DataFrame::create(_["mgrs"] = mgrs_string,
-                             _["zone"] = zone,
-                             _["hemisphere"] = std::string(h_buf),
-                             _["easting"] = easting,
-                             _["northing"] = northing,
-                             _["stringsAsFactors"] = false));
+    return(
+      DataFrame::create(
+        _["zone"] = zonev,
+        _["hemisphere"] = hemispherev,
+        _["easting"] = eastingv,
+        _["northing"] = northingv,
+        _["stringsAsFactors"] = false
+      )
+    );
   }
+
 }
 
 //' Convert UPS to MGRS
@@ -183,35 +231,63 @@ String ups_to_mgrs(std::string hemisphere,
 //' Convert MGRS to UPS
 //'
 //' @md
-//' @param mgrs_string an MGRS string
+//' @note vectorized
+//' @param mgrs_string a character vector of MGRS strings
+//' @param include_mgrs_ref if `TRUE` the data frame returned fill include
+//'        the MGRS reference in a column named `mgrs`. Default: `TRUE`.
 //' @return `data.frame`
 //' @export
 //' @examples
 //' mgrs_to_ups("ZGC2677330125")
 // [[Rcpp::export]]
-DataFrame mgrs_to_ups(std::string mgrs_string) {
+DataFrame mgrs_to_ups(std::vector < std::string > mgrs_string, bool include_mgrs_ref = true) {
 
   char h_buf[80];
   double easting, northing;
   long ret;
+  StringVector hemispherev = StringVector(mgrs_string.size());
+  NumericVector eastingv = NumericVector(mgrs_string.size());
+  NumericVector northingv = NumericVector(mgrs_string.size());
 
-  ret = Convert_MGRS_To_UPS((char *)mgrs_string.c_str(), h_buf, &easting, &northing);
+  for (unsigned int i=0; i<mgrs_string.size(); i++) {
 
-  if (ret != MGRS_NO_ERROR) {
-    Rcpp::warning("Error converting MGRS to UPS");
-    return(DataFrame::create(_["mgrs"] = mgrs_string,
-                             _["hemisphere"] = NA_STRING,
-                             _["easting"] = NA_REAL,
-                             _["northing"] = NA_REAL,
-                             _["stringsAsFactors"] = false));
+    ret = Convert_MGRS_To_UPS((char *)mgrs_string[i].c_str(), h_buf, &easting, &northing);
+
+    if (ret != MGRS_NO_ERROR) {
+      Rcpp::warning("Error converting MGRS to UGM");
+      hemispherev[i] = NA_STRING;
+      eastingv[i] = NA_REAL;
+      northingv[i] = NA_REAL;
+    } else {
+      h_buf[1] = '\0';
+      hemispherev[i] = std::string(h_buf);
+      eastingv[i] = easting;
+      northingv[i] = northing;
+    }
+
+  }
+
+  if (include_mgrs_ref) {
+    return(
+      DataFrame::create(
+        _["mgrs"] = mgrs_string,
+        _["hemisphere"] = hemispherev,
+        _["easting"] = eastingv,
+        _["northing"] = northingv,
+        _["stringsAsFactors"] = false
+      )
+    );
   } else {
-    h_buf[1] = '\0';
-    return(DataFrame::create(_["mgrs"] = mgrs_string,
-                             _["hemisphere"] = std::string(h_buf),
-                             _["easting"] = easting,
-                             _["northing"] = northing,
-                             _["stringsAsFactors"] = false));
+    return(
+      DataFrame::create(
+        _["hemisphere"] = hemispherev,
+        _["easting"] = eastingv,
+        _["northing"] = northingv,
+        _["stringsAsFactors"] = false
+      )
+    );
   }
+
 }
 
 //' Convert UPS to Latitude/Longitude

tests/testthat/test-mgrs.R

@@ -42,4 +42,22 @@ test_that("we can convert things", {
                                                               "easting",  "northing"),
                          row.names = c(NA, -1L), class = "data.frame"))
 
+  data.frame(
+    id = 1:50,
+    mgrs = c("16SEB20", "09UXQ25", "12SVC48", "15SWU64", "11SKA54", "13SDC58",
+             "18TYM20", "18SWH08", "17RML38", "17SKR77", "09RYR61", "12TTP62",
+             "16TBK93", "16TEK73", "15TVG64", "14SNH75", "16SFG94", "15RWP68",
+             "19TEL05", "18SUJ54", "19TBG89", "16TFN87", "15TUM73", "16SBB31",
+             "15SWC44", "12TXS28", "14TML57", "11SND12", "19TCJ00", "18SWK62",
+             "13SDU11", "18TVN87", "17SQV22", "14TMT13", "17TLE65", "14SPE73",
+             "10TGP36", "18TTL93", "19TCG20", "17SNT42", "14TMQ40", "16SEE44",
+             "14RNV27", "12SVJ72", "18TXQ90", "17SQB46", "11TKN95", "17SNC25",
+             "16TBQ64", "13TCH16"),
+    stringsAsFactors = FALSE
+  ) -> sample_dta
+
+  expect_equal(ncol(mgrs_to_latlng(sample_dta$mgrs, include_mgrs_ref = FALSE)), 2)
+  expect_equal(ncol(mgrs_to_utm("48PUV7729883034", include_mgrs_ref = FALSE)), 4)
+  expect_equal(ncol(mgrs_to_ups("ZGC2677330125", include_mgrs_ref = FALSE)), 3)
+
 })