0.0.2

R/basemap_dem.R

@@ -4,24 +4,26 @@
 #' `basemap_dem` adds a digital elevation model (DEM) raster map of China as a layer to ggplot2.
 #' The function ensures the output map remains rectangular, regardless of the chosen projection.
 #' It supports displaying the DEM either within China's boundary or in a larger rectangular area
-#' around China.
+#' around China. Users can provide their own DEM data using the `data` parameter, or the default
+#' built-in DEM data will be used.
 #'
+#' @param data Optional. A `terra` raster object for custom DEM data. If `NULL` (default), the function
+#'   uses the built-in DEM data (`gebco_2024.tif`).
 #' @param crs Coordinate reference system (CRS) for the projection. Defaults to the CRS of the DEM data.
 #'   Users can specify other CRS strings (e.g., `"EPSG:4326"` or custom projections).
 #' @param within_china Logical. If `TRUE`, displays only the DEM within China's boundary.
-#'   If `FALSE`, displays the DEM for a larger rectangular area around China. Default is `FALSE`.
+#'   If `FALSE`, displays the DEM for a larger rectangular area around China, determined by `extent`. Default is `FALSE`.
+#' @param extent Numeric vector of length 4. Specifies the rectangular bounds in WGS84 CRS (`xmin, xmax, ymin, ymax`).
+#'   Used when `within_china = FALSE`. Default is `c(77, 130, -10, 60)`.
 #' @param maxcell Maximum number of cells for rendering (to improve performance). Defaults to `1e6`.
 #' @param na.rm Logical. If `TRUE`, removes missing values. Default is `FALSE`.
 #' @param ... Additional parameters passed to `geom_spatraster`.
 #'
-#' @seealso
-#' \code{\link[ggmapcn]{geom_boundary_cn}}
-#'
 #' @examples
 #' # Define Azimuthal Equidistant projection centered on China
 #' china_proj <- "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs"
 #'
-#' # Example 1: Display full rectangular area around China
+#' # Example 1: Display full rectangular area around China using default extent
 #' ggplot() +
 #'   basemap_dem(within_china = FALSE) +
 #'   tidyterra::scale_fill_hypso_tint_c(
@@ -30,7 +32,12 @@
 #'   ) +
 #'   theme_minimal()
 #'
-#' # Example 2: Display only China's DEM and boundaries
+#' # Example 2: Display DEM with custom extent
+#' ggplot() +
+#'   basemap_dem(within_china = FALSE, extent = c(105, 123, 2, 23))+
+#'   theme_minimal()
+#'
+#' # Example 3: Display only China's DEM and boundaries using built-in DEM data
 #' ggplot() +
 #'   basemap_dem(crs = china_proj, within_china = TRUE) +
 #'   geom_boundary_cn(crs = china_proj) +
@@ -43,18 +50,25 @@
 #'   theme_minimal()
 #'
 #' @export
-basemap_dem <- function(crs = NULL,
+basemap_dem <- function(data = NULL,
+                        crs = NULL,
                         within_china = FALSE,
+                        extent = c(77, 130, -10, 60),
                         maxcell = 1e6,
                         na.rm = FALSE,
                         ...) {
 
-  # Load DEM raster of Asia from the package's extdata directory
-  dem_path <- system.file("extdata", "gebco_2024.tif", package = "ggmapcn")
-  if (dem_path == "") {
-    stop("DEM file not found. Ensure 'gebco_2024.tif' is in the package's extdata folder.")
+  # If no custom data is provided, use the default DEM raster of Asia
+  if (is.null(data)) {
+    dem_path <- system.file("extdata", "gebco_2024.tif", package = "ggmapcn")
+    if (dem_path == "") {
+      stop("DEM file not found. Ensure 'gebco_2024.tif' is in the package's extdata folder.")
+    }
+    dem_raster <- terra::rast(dem_path)
+  } else {
+    # Use the user-provided custom DEM data
+    dem_raster <- data
   }
-  dem_raster <- terra::rast(dem_path)
 
   if (within_china) {
     # Load China's boundary for masking
@@ -78,9 +92,8 @@ basemap_dem <- function(crs = NULL,
     # Mask DEM with China's boundary
     dem_raster <- terra::crop(dem_raster, china_boundary, mask = TRUE)
   } else {
-    # Default rectangular bounding box around China
-    china_extent <- c(60, 140, 0, 55) # Approximate bounds for China and surroundings
-    bbox <- terra::ext(china_extent)
+    # Use the specified extent for cropping
+    bbox <- terra::ext(extent)
     bbox <- terra::vect(bbox, crs = "EPSG:4326")
 
     if (!is.null(crs)) {

R/coord_proj.R

@@ -43,6 +43,17 @@
 #'   ) +
 #'   theme_minimal()
 #'
+#' # Example 3: Display a map of the South China Sea Islands with a custom projection
+#' ggplot() +
+#'   geom_boundary_cn() +
+#'   theme_bw() +
+#'   coord_proj(
+#'     crs = china_proj,
+#'     expand = FALSE,
+#'     xlim = c(105, 125),
+#'     ylim = c(2, 26)
+#'   )
+#'
 #' @seealso
 #' \code{\link[ggplot2:coord_sf]{ggplot2::coord_sf}}, \code{\link[ggmapcn:geom_world]{geom_world}}
 #'