diff --git a/.Rbuildignore b/.Rbuildignore index 84884e2..b93abef 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,3 +1,4 @@ +^LICENSE\.md$ ^.*\.Rproj$ ^\.Rproj\.user$ ^\.travis\.yml$ diff --git a/.travis.yml b/.travis.yml index 319ae9d..0a073d4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -21,7 +21,3 @@ after_success: notifications: email: - bob@rud.is - irc: - channels: - - "104.236.112.222#builds" - nick: travisci diff --git a/DESCRIPTION b/DESCRIPTION index a98434c..f64ce6a 100644 --- a/DESCRIPTION +++ b/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 -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 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b6a10f1 --- /dev/null +++ b/LICENSE @@ -0,0 +1,2 @@ +YEAR: 2019 +COPYRIGHT HOLDER: Bob Rudis diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..c36552c --- /dev/null +++ b/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. diff --git a/NAMESPACE b/NAMESPACE index 563db1e..d9b41fe 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index 22ba2c1..c156c19 100644 --- a/NEWS.md +++ b/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 diff --git a/R/RcppExports.R b/R/RcppExports.R index 3ded5aa..f1aeed9 100644 --- a/R/RcppExports.R +++ b/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 diff --git a/R/mgrs-package.R b/R/mgrs-package.R index 5946094..88555ac 100644 --- a/R/mgrs-package.R +++ b/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) diff --git a/R/utils-pipe.R b/R/utils-pipe.R new file mode 100644 index 0000000..fb8c818 --- /dev/null +++ b/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 diff --git a/README.Rmd b/README.Rmd index 5147ab8..fcd5de4 100644 --- a/README.Rmd +++ b/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 . Decent reference on MGRS & UTM (Universal Transverse Mercator): . +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 -- Add in support for the other MGRS conversion thingys -- 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 diff --git a/README.md b/README.md index 97eb51f..df176f7 100644 --- a/README.md +++ b/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 . Decent reference on MGRS & UTM (Universal Transverse Mercator): . +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 - - Add in support for the other MGRS conversion - thingys - - 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 + ## + ## 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") ``` - + ## Code of Conduct diff --git a/README_files/figure-gfm/unnamed-chunk-4-1.png b/README_files/figure-gfm/unnamed-chunk-4-1.png index 8af565f..bd038b8 100644 Binary files a/README_files/figure-gfm/unnamed-chunk-4-1.png and b/README_files/figure-gfm/unnamed-chunk-4-1.png differ diff --git a/README_files/figure-gfm/unnamed-chunk-5-1.png b/README_files/figure-gfm/unnamed-chunk-5-1.png new file mode 100644 index 0000000..a66fe31 Binary files /dev/null and b/README_files/figure-gfm/unnamed-chunk-5-1.png differ diff --git a/inst/COPYRIGHTS b/inst/COPYRIGHTS new file mode 100644 index 0000000..2c61aef --- /dev/null +++ b/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 () 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. + * + /* \ No newline at end of file diff --git a/man/figures/mgrs-grid.png b/man/figures/mgrs-grid.png new file mode 100644 index 0000000..7691bb7 Binary files /dev/null and b/man/figures/mgrs-grid.png differ diff --git a/man/mgrs.Rd b/man/mgrs.Rd index bcd6f92..a278cce 100644 --- a/man/mgrs.Rd +++ b/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) diff --git a/man/mgrs_to_latlng.Rd b/man/mgrs_to_latlng.Rd index dd01a2a..a83bd15 100644 --- a/man/mgrs_to_latlng.Rd +++ b/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} diff --git a/man/mgrs_to_ups.Rd b/man/mgrs_to_ups.Rd index 774a8f7..bae588d 100644 --- a/man/mgrs_to_ups.Rd +++ b/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") } diff --git a/man/mgrs_to_utm.Rd b/man/mgrs_to_utm.Rd index eac2e42..6adcb90 100644 --- a/man/mgrs_to_utm.Rd +++ b/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") } diff --git a/man/pipe.Rd b/man/pipe.Rd new file mode 100644 index 0000000..b7daf6a --- /dev/null +++ b/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} diff --git a/src/RcppExports.cpp b/src/RcppExports.cpp index f877e5f..d9252af 100644 --- a/src/RcppExports.cpp +++ b/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} diff --git a/src/main.cpp b/src/main.cpp index 68b19f8..b6634b0 100644 --- a/src/main.cpp +++ b/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, 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 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) + })