init

R/sample-tiles.R

@@ -0,0 +1,128 @@
+#' Get Path to Sample PMTiles File
+#'
+#' @description
+#' Returns the path to a sample PMTiles file for demos and testing.
+#' On first use, downloads a small regional extract to the user's cache
+#' directory.
+#'
+#' @param region Character. Region to download. Currently only "sf-bay"
+#'   (San Francisco Bay Area) is available. Default is "sf-bay".
+#' @param cache_dir Character. Directory to cache the downloaded file.
+#'   Default uses \code{tools::R_user_dir()}.
+#' @param force_download Logical. Force re-download even if cached.
+#'   Default is FALSE.
+#'
+#' @return Character. Path to the PMTiles file.
+#'
+#' @details
+#' The sample tiles are hosted on GitHub releases and downloaded on first use.
+#' Subsequent calls use the cached file. The SF Bay Area extract is
+#' approximately 10-15MB and covers the greater San Francisco region at all
+#' zoom levels.
+#'
+#' For production use, consider self-hosting your own PMTiles file. See
+#' \code{vignette("getting-started")} for options.
+#'
+#' @examples
+#' \dontrun{
+#' library(leaflet)
+#' library(protomapr)
+#'
+#' # Use sample tiles for demos (downloads on first use)
+#' leaflet() %>%
+#'   setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
+#'   addProtomaps(url = protomaps_sample_tiles())
+#' }
+#'
+#' @seealso \code{\link{protomaps_clear_cache}}, \code{\link{protomaps_url}}
+#' @export
+protomaps_sample_tiles <- function(region = "sf-bay",
+                                   cache_dir = NULL,
+                                   force_download = FALSE) {
+
+  region <- match.arg(region, choices = c("sf-bay"))
+
+  if (is.null(cache_dir)) {
+    cache_dir <- tools::R_user_dir("protomapr", which = "cache")
+  }
+
+  if (!dir.exists(cache_dir)) {
+    dir.create(cache_dir, recursive = TRUE)
+  }
+
+  filename <- sprintf("protomapr-sample-%s.pmtiles", region)
+  local_path <- file.path(cache_dir, filename)
+
+  if (file.exists(local_path) && !force_download) {
+    message("Using cached sample tiles: ", local_path)
+    return(local_path)
+  }
+
+  base_url <- "https://github.com/evmo/protomapr/releases/download"
+  version <- "sample-tiles-v1"
+  download_url <- sprintf("%s/%s/%s", base_url, version, filename)
+
+  message("Downloading sample tiles (~10MB)...")
+  message("Source: ", download_url)
+
+ tryCatch({
+    utils::download.file(
+      url = download_url,
+      destfile = local_path,
+      mode = "wb",
+      quiet = FALSE
+    )
+    message("Downloaded to: ", local_path)
+  }, error = function(e) {
+    stop(
+      "Failed to download sample tiles.\n",
+      "Error: ", conditionMessage(e), "\n",
+      "Try again later or use protomaps_url() with an API key instead.",
+      call. = FALSE
+    )
+  })
+
+  local_path
+}
+
+
+#' Clear Cached Sample Tiles
+#'
+#' @description
+#' Removes cached sample PMTiles files to free disk space.
+#'
+#' @param cache_dir Character. Cache directory. Default uses same as
+#'   \code{\link{protomaps_sample_tiles}}.
+#'
+#' @return Invisibly returns TRUE if files were removed, FALSE otherwise.
+#'
+#' @examples
+#' \dontrun{
+#' # Clear all cached tiles
+#' protomaps_clear_cache()
+#' }
+#'
+#' @seealso \code{\link{protomaps_sample_tiles}}
+#' @export
+protomaps_clear_cache <- function(cache_dir = NULL) {
+  if (is.null(cache_dir)) {
+    cache_dir <- tools::R_user_dir("protomapr", which = "cache")
+  }
+
+  if (!dir.exists(cache_dir)) {
+    message("Cache directory does not exist: ", cache_dir)
+    return(invisible(FALSE))
+  }
+
+  files <- list.files(cache_dir, pattern = "\\.pmtiles$", full.names = TRUE)
+
+  if (length(files) == 0) {
+    message("No cached tiles found.")
+    return(invisible(FALSE))
+  }
+
+  unlink(files)
+  message(sprintf("Removed %d cached file(s).", length(files)))
+
+  invisible(TRUE)
+}