Implement default crs for non-sf objects in coord_sf(). (#3659)

* Implement default crs for non-sf objects in coord_sf().

* make limits work

* cleanup code, write documentation

* more accurately specify CRS

* handle missing or infinite values in sf_transform_xy().

* fix package build

* properly reset bbox at beginning of plot generation

* cleanup

* check that the coord is of type CoordSf before
calling its unique function

* scale limit improvements

* Register bounding box even for stat_sf_coordinates. Gives better default limits.

* finalize handling of limits, improve documentation

* unit tests for new coord_sf() features

* alternative limit methods

* ensure point data is always numeric

* expand documentation

* delete space

* capitalize crs

* check against incorrect mapping

* update docs

* more limits methods

* better limits methods

* simplify error message

* fix error message if scale limits inversion problem

* reword warnings and error messages.

Author: clauswilke

NAMESPACE

@@ -592,6 +592,7 @@ export(scale_y_sqrt)
 export(scale_y_time)
 export(sec_axis)
 export(set_last_plot)
+export(sf_transform_xy)
 export(should_stop)
 export(stage)
 export(standardise_aes_names)

NEWS.md

@@ -11,6 +11,16 @@ This is a small release focusing on fixing regressions introduced in 3.3.1.
 
 * `annotation_raster()` adds support for native rasters. For large rasters,
   native rasters render significantly faster than arrays (@kent37, #3388)
+
+* `coord_sf()` now has an argument `default_crs` that specifies the coordinate
+  reference system (CRS) for non-sf layers and scale/coord limits. This argument
+  defaults to the World Geodetic System 1984 (WGS84), which means x and y positions
+  are interpreted as longitude and latitude. This is a potentially breaking change
+  for users who use projected coordinates in non-sf layers or in limits. Setting
+  `default_crs = NULL` recovers the old behavior. Further, authors of extension
+  packages implementing `stat_sf()`-like functionality are encouraged to look at the
+  source code of `stat_sf()`'s `compute_group()` function to see how to provide
+  scale-limit hints to `coord_sf()` (@clauswilke, #3659).
 
 * Facet strips now have dedicated position-dependent theme elements 
   (`strip.text.x.top`, `strip.text.x.bottom`, `strip.text.y.left`, 

R/annotation-map.r

@@ -1,34 +1,60 @@
 #' @include geom-map.r
 NULL
 
-#' Annotation: a maps
+#' Annotation: a map
 #'
-#' Display a fixed map on a plot.
+#' Display a fixed map on a plot. This function predates the [`geom_sf()`]
+#' framework and does not work with sf geometry columns as input. However,
+#' it can be used in conjunction with `geom_sf()` layers and/or
+#' [`coord_sf()`] (see examples).
 #'
-#' @param map data frame representing a map.  Most map objects can be
-#'   converted into the right format by using [fortify()]
-#' @param ... other arguments used to modify aesthetics
+#' @param map Data frame representing a map. See [`geom_map()`] for
+#'   details.
+#' @param ... Other arguments used to modify visual parameters, such as
+#'   `colour` or `fill`.
 #' @export
 #' @examples
-#' if (require("maps")) {
-#' usamap <- map_data("state")
+#' \dontrun{
+#' if (requireNamespace("maps", quietly = TRUE)) {
+#' # location of cities in North Carolina
+#' df <- data.frame(
+#'   name = c("Charlotte", "Raleigh", "Greensboro"),
+#'   lat = c(35.227, 35.772, 36.073),
+#'   long = c(-80.843, -78.639, -79.792)
+#' )
 #'
-#' seal.sub <- subset(seals, long > -130 & lat < 45 & lat > 40)
-#' ggplot(seal.sub, aes(x = long, y = lat)) +
-#'   annotation_map(usamap, fill = NA, colour = "grey50") +
-#'   geom_segment(aes(xend = long + delta_long, yend = lat + delta_lat))
-#' }
+#' p <- ggplot(df, aes(x = long, y = lat)) +
+#'   annotation_map(
+#'     map_data("state"),
+#'     fill = "antiquewhite", colour = "darkgrey"
+#'   ) +
+#'   geom_point(color = "blue") +
+#'   geom_text(
+#'     aes(label = name),
+#'     hjust = 1.105, vjust = 1.05, color = "blue"
+#'   )
 #'
-#' if (require("maps")) {
-#' seal2 <- transform(seal.sub,
-#'   latr = cut(lat, 2),
-#'   longr = cut(long, 2))
+#' # use without coord_sf() is possible but not recommended
+#' p + xlim(-84, -76) + ylim(34, 37.2)
 #'
-#' ggplot(seal2,  aes(x = long, y = lat)) +
-#'   annotation_map(usamap, fill = NA, colour = "grey50") +
-#'   geom_segment(aes(xend = long + delta_long, yend = lat + delta_lat)) +
-#'   facet_grid(latr ~ longr, scales = "free", space = "free")
-#' }
+#' if (requireNamespace("sf", quietly = TRUE)) {
+#' # use with coord_sf() for appropriate projection
+#' p +
+#'   coord_sf(
+#'     crs = st_crs(3347),
+#'     xlim = c(-84, -76),
+#'     ylim = c(34, 37.2)
+#'   )
+#'
+#' # you can mix annotation_map() and geom_sf()
+#' nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
+#' p +
+#'   geom_sf(
+#'     data = nc, inherit.aes = FALSE,
+#'     fill = NA, color = "black", size = 0.1
+#'   ) +
+#'   coord_sf(crs = st_crs(3347))
+#' }}}
 annotation_map <- function(map, ...) {
   # Get map input into correct form
   if (!is.data.frame(map)) {