hrbrmstr / mgrs

:globe_with_meridians: An R Package to Convert 'MGRS' (Military Grid Reference System) References From/To Other Coordiante Systems

mgrs

Convert ‘MGRS’ (‘Military Grid Reference System’) Coordinates 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 convert ‘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.

CC-BY-SA 3.0

What’s Inside The Tin

The following functions are implemented:

• latlng_to_mgrs: Convert latitude/longitude to MGRS string
• mgrs_precision: Return MGRS grid reference precision (in meters)
• 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_latlng: Convert UPS to Latitude/Longitude
• ups_to_mgrs: Convert UPS to MGRS
• utm_to_latlng: Convert UTM to Latitude/Longitude
• utm_to_mgrs: Convert UTM to MGRS

Installation

remotes::install_github("hrbrmstr/mgrs")

NOTE: To use the ‘remotes’ install options you will need to have the {remotes} package installed.

Usage

library(mgrs)
library(sf)
library(ggplot2)
library(hrbrthemes)

# current version
packageVersion("mgrs")
## [1] '0.2.4'

Basics

mgrs_to_latlng("33UXP04")
##      mgrs      lat      lng
## 1 33UXP04 48.20535 16.34593

mgrs_to_latlng("33UXP04") |> 
  sf::st_as_sf(
    coords = c("lng", "lat"),
    crs = 4326
  )
## Simple feature collection with 1 feature and 1 field
## Geometry type: POINT
## Dimension:     XY
## Bounding box:  xmin: 16.34593 ymin: 48.20535 xmax: 16.34593 ymax: 48.20535
## Geodetic CRS:  WGS 84
##      mgrs                  geometry
## 1 33UXP04 POINT (16.34593 48.20535)

latlng_to_mgrs(48.20535, 16.34593)
## [1] "33UXP0000040000"

mgrs_to_latlng("33UXP0500444996")
##              mgrs      lat      lng
## 1 33UXP0500444996 48.24947 16.41449

latlng_to_mgrs(48.24948, 16.41449)
## [1] "33UXP0500344996"

mgrs_to_latlng("33UXP0500444996") |> 
  sf::st_as_sf(
    coords = c("lng", "lat"),
    crs = 4326
  )
## Simple feature collection with 1 feature and 1 field
## Geometry type: POINT
## Dimension:     XY
## Bounding box:  xmin: 16.41449 ymin: 48.24947 xmax: 16.41449 ymax: 48.24947
## Geodetic CRS:  WGS 84
##              mgrs                  geometry
## 1 33UXP0500444996 POINT (16.41449 48.24947)

mgrs_to_latlng("24XWT783908")
##          mgrs      lat       lng
## 1 24XWT783908 83.62738 -32.66879

mgrs_to_latlng("24XWT783908") |> 
  sf::st_as_sf(
    coords = c("lng", "lat"),
    crs = 4326
  )
## Simple feature collection with 1 feature and 1 field
## Geometry type: POINT
## Dimension:     XY
## Bounding box:  xmin: -32.66879 ymin: 83.62738 xmax: -32.66879 ymax: 83.62738
## Geodetic CRS:  WGS 84
##          mgrs                   geometry
## 1 24XWT783908 POINT (-32.66879 83.62738)

latlng_to_mgrs(83.62738, -32.66879)
## [1] "25XEN0410486507"

utm_to_mgrs(48, "N", 377299, 1483035)
## [1] "48PUV7729983035"

mgrs_to_utm("48PUV7729883034")
##              mgrs zone hemisphere easting northing
## 1 48PUV7729883034   48          N  377298  1483034

ups_to_mgrs("N", 2426773, 1530125)
## [1] "ZGC2677330125"

mgrs_to_ups("ZGC2677330125")
##            mgrs hemisphere easting northing
## 1 ZGC2677330125          N 2426773  1530125

c(
  "4Q", "4QFJ", "4QFJ16", 
  "4QFJ1267", "4QFJ123678",
  "4QFJ12346789", "4QFJ1234567890"
) -> grefs

mgrs_precision(grefs)
## # A tibble: 7 × 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

Usage in the {tidyverse}

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"
    )
) -> sample_dta

sample_dta |> 
  dplyr::mutate(
    x = lapply(mgrs, mgrs_to_latlng, include_mgrs_ref = FALSE)
  ) |>
  tidyr::unnest(x) |> 
  sf::st_as_sf(
    coords = c("lng", "lat"),
    crs = 4326
  )
## Simple feature collection with 50 features and 2 fields
## Geometry type: POINT
## Dimension:     XY
## Bounding box:  xmin: -127.353 ymin: 27.84288 xmax: -69 ymax: 49.19105
## Geodetic CRS:  WGS 84
## # A tibble: 50 × 3
##       id mgrs                geometry
##  * <int> <chr>            <POINT [°]>
##  1     1 16SEB20 (-86.78701 32.53717)
##  2     2 09UXQ25  (-127.353 49.19105)
##  3     3 12SVC48 (-111.6509 34.15921)
##  4     4 15SWU64 (-92.34486 34.70027)
##  5     5 11SKA54  (-119.7903 36.4727)
##  6     6 13SDC58 (-105.5747 38.66717)
##  7     7 18TYM20 (-72.36334 41.52143)
##  8     8 18SWH08       (-75 38.66858)
##  9     9 17RML38  (-81.7109 27.84288)
## 10    10 17SKR77 (-83.44116 32.24313)
## # ℹ 40 more rows

Visual Verification

# precision == 1

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"
) -> mgrs_conus_state_centers

mgrs_conus_state_centers |> 
  mgrs_to_latlng() |>
  st_as_sf(
    coords = c("lng", "lat"),
    crs = 4326
  ) |> 
  ggplot() +
  geom_sf(
    shape = 22,
    ize = 2, color = "black", 
    fill = "white"
  ) +
  coord_sf(
    crs = 5070
  ) +
  theme_ft_rc(grid="XY")

mgrs Metrics

Lang	# Files	(%)	LoC	(%)	Blank lines	(%)	# Lines	(%)
C	5	0.15	1847	0.38	334	0.34	918	0.26
C++	2	0.06	346	0.07	64	0.07	99	0.03
C/C++ Header	5	0.15	188	0.04	74	0.08	546	0.16
R	5	0.15	41	0.01	17	0.02	198	0.06
SUM	17	0.50	2422	0.50	489	0.50	1761	0.50

{cloc} 📦 metrics for mgrs

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

mgrs's Issues

Area of MGRS tiles

Dear Bob,
Thank you so very much for the mgrs package! I am doing a number of spatial aggregations in my current projects and your package has been extremely helpful.

I was wondering if you would help me with this question. Since the MGRS system is not an equal-area gridding system, the area of individual MGRS tiles at the same resolution (10m^2, 100m^2 etc.) differ from each other. Do you know where I can find the actual area of each MGRS tile?

Thanks very much for your time!
Best,
Jyoti

Error in FUN(X[[i]], ...) : tinyformat: Too many conversion specifiers in format string

clean_data %>% mutate(x = lapply(MGRS, mgrs::mgrs_to_latlng, include_mgrs_ref = FALSE)) %>% tidyr::unnest(x) -> new_df
results in "Error in FUN(X[[i]], ...) : tinyformat: Too many conversion specifiers in format string"
I am not familiar with this error, I'm not sure where to go from here. Thanks!

CRAN?

Hello there!

Do you plan on submitting {mgrs} to CRAN?

mebbe migrate to https://docs.rs/geomorph/1.0.0/geomorph/mgrs/struct.Mgrs.html ?

Problem Installing Package

I am currently unable to install this package after attempting to install it in a new version of R. The error says that 'PI' is an undeclared identifier. The full error message has been included below. I believe the error occurs for each of the main functions included in the src/main.cpp file.

I received the same message for each of the following commands:

remotes::install_github("hrbrmstr/mgrs")

install.packages("mgrs", repos = "https://cinc.rud.is")

`main.cpp:41:42: error: use of undeclared identifier 'PI'
      lat_vec[i] = degrees ? lat * 180.0/PI : lat;
                                         ^

main.cpp:42:42: error: use of undeclared identifier 'PI'
      lng_vec[i] = degrees ? lng * 180.0/PI : lng;
                                         ^

main.cpp:86:17: error: use of undeclared identifier 'PI'
    latitude *= PI / 180.0;
                ^

main.cpp:87:18: error: use of undeclared identifier 'PI'
    longitude *= PI / 180.0;
                 ^

main.cpp:322:40: error: use of undeclared identifier 'PI'
      _["lat"] = degrees ? lat * 180.0/PI : lat,
                                       ^

main.cpp:323:40: error: use of undeclared identifier 'PI'
      _["lng"] = degrees ? lng * 180.0/PI : lng
                                       ^

main.cpp:361:40: error: use of undeclared identifier 'PI'
      _["lat"] = degrees ? lat * 180.0/PI : lat,
                                       ^

main.cpp:362:40: error: use of undeclared identifier 'PI'
      _["lng"] = degrees ? lng * 180.0/PI : lng
                                       ^

8 errors generated.
make: *** [main.o] Error 1
ERROR: compilation failed for package ‘mgrs’` 

My R and system information is included below. I also received the same error after trying to install the package on a Posit Cloud Installation. I have used this package extensively on previous versions of R and never had this issue.

platform       x86_64-apple-darwin17.0     
arch           x86_64                      
os             darwin17.0                  
system         x86_64, darwin17.0          
status                                     
major          4                           
minor          2.1                         
year           2022                        
month          06                          
day            23                          
svn rev        82513                       
language       R                           
version.string R version 4.2.1 (2022-06-23)
nickname       Funny-Looking Kid    

Thank you for your help and suggestions! This package has been incredibly helpful for my research!

Feature Request: Passing Data Frames to mgrs_to_latlng

I was wondering if you had given any thought into making it possible to use columns from a data frame as the input to themgrs_to_latlng function rather than just strings? This would make it possible to use the function directly within a mutate call. I have included the code to a rough function that makes it possible to convert vectors to lat and long coordinates. Thanks for all the work that you've put into this package. It's really helpful!

#----- Function

mgrs_df_convert <- function(df, mgrs_coord_vector, coord) {
  
  library(mgrs)

  utm_vector <- df[[mgrs_coord_vector]]
  lat_long_vectors <- mgrs::mgrs_to_latlng(utm_vector)
  lat_vectors <- lat_long_vectors[,c(2)]
  long_vectors <- lat_long_vectors[,c(3)]
  
  if (coord == "lat") {
    print(lat_vectors)
  } else if (coord == "long") {
    print(long_vectors)
  } else {
    print("Error: coord needs to specify lat or long")
  }
  
}

#---- Example 

sample_dta <- tibble(
  id = 1:4, 
  mgrs = c("48QYD448540", "48QYD454535", "48QYD458529", "48QYD442547")
)

mutate_test_dta <- sample_dta %>% 
  mutate(lat_test = mgrs_df_convert(., "mgrs", "lat"),
         long_test = mgrs_df_convert(., "mgrs", "long"))


glimpse(mutate_test_dta)

Release packaged version

Hi there-

Would you be able to release this as a versioned tar.gz? I'm trying to add it to conda-forge, so more people can access it easily, but in order to do that, I need a tarball and a version number.

Thanks in advance,

Andrew

Compiler errors for some of the nominated installer mechanisms

Recent difficulty in installing via some some but not all of the package copies:
These successes and failures on:
R version 4.3.1 (2023-06-16)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 18.04.6 LTS
But my investigation was pursuant to a SO Q that reported on a Windoze bo and who also had success with the same method..

Success with:
remotes::install_github("hrbrmstr/mgrs")

Failure with:
remotes::install_git("https://git.rud.is/hrbrmstr/mgrs.git")
...
curity -Wdate-time -D_FORTIFY_SOURCE=2 -Wno-ignored-attributes -c main.cpp -o main.o
main.cpp: In function ‘Rcpp::DataFrame mgrs_to_latlng(std::vector<std::__cxx11::basic_string >, bool, bool)’:
main.cpp:41:42: error: ‘PI’ was not declared in this scope
lat_vec[i] = degrees ? lat * 180.0/PI : lat;

And failure with:
install.packages("mgrs", repos = "https://cinc.rud.is")
...
curity -Wdate-time -D_FORTIFY_SOURCE=2 -Wno-ignored-attributes -c main.cpp -o main.o
main.cpp: In function ‘Rcpp::DataFrame mgrs_to_latlng(std::vector<std::__cxx11::basic_string >, bool, bool)’:
main.cpp:41:42: error: ‘PI’ was not declared in this scope
lat_vec[i] = degrees ? lat * 180.0/PI : lat;