init

R/colors.R

@@ -0,0 +1,147 @@
+#' Create custom color overrides
+#'
+#' @description
+#' Creates a list of color overrides that can be applied to a built-in flavor.
+#' This is the recommended way to customize map colors while keeping the
+#' proper rendering rules (zoom handling, polygon simplification, etc.).
+#'
+#' @param background Background color
+#' @param earth Land/earth color
+#' @param water Water color
+#' @param park Park/green space color (also called park_a or park_b)
+#' @param wood Forest/woodland color (also called wood_a or wood_b)
+#' @param hospital Hospital area color
+#' @param industrial Industrial area color
+#' @param school School/university area color
+#' @param beach Beach color
+#' @param glacier Glacier color
+#' @param highway Highway road color
+#' @param major Major road color
+#' @param minor Minor road color
+#' @param city_label City label color
+#' @param state_label State/region label color
+#' @param country_label Country label color
+#' @param ocean_label Ocean label color
+#' @param ... Additional color properties
+#'
+#' @return A list of color overrides to pass to \code{\link{addProtomaps}}.
+#'
+#' @examples
+#' # Simple earth and water colors
+#' pmColors(earth = "#d3d3d3", water = "#1a3a5c")
+#'
+#' # Dark theme with custom colors
+#' pmColors(
+#'   background = "#1a1a2e",
+#'   earth = "#1a1a2e",
+#'   water = "#16213e",
+#'   park = "#1f4037",
+#'   highway = "#4a4a6a"
+#' )
+#'
+#' # Minimal grayscale
+#' pmColors(
+#'   background = "#ffffff",
+#'   earth = "#f5f5f5",
+#'   water = "#e0e0e0"
+#' )
+#'
+#' @seealso \code{\link{addProtomaps}}, \code{\link{protomaps_colors}}
+#' @export
+pmColors <- function(background = NULL,
+                      earth = NULL,
+                      water = NULL,
+                      park = NULL,
+                      wood = NULL,
+                      hospital = NULL,
+                      industrial = NULL,
+                      school = NULL,
+                      beach = NULL,
+                      glacier = NULL,
+                      highway = NULL,
+                      major = NULL,
+                      minor = NULL,
+                      city_label = NULL,
+                      state_label = NULL,
+                      country_label = NULL,
+                      ocean_label = NULL,
+                      ...) {
+
+  # Start with extra args, add named params, remove NULLs
+  colors <- c(
+    list(...),
+    list(
+      background = background, earth = earth, water = water,
+      hospital = hospital, industrial = industrial, school = school,
+      beach = beach, glacier = glacier, highway = highway, major = major,
+      city_label = city_label, state_label = state_label,
+      country_label = country_label, ocean_label = ocean_label,
+      # Expand paired colors
+      park_a = park, park_b = park,
+      wood_a = wood, wood_b = wood,
+      minor_a = minor, minor_b = minor
+    )
+  )
+  colors[!vapply(colors, is.null, logical(1))]
+}
+
+
+#' Protomaps Color Properties Reference
+#'
+#' @description
+#' Reference documentation for all available color properties that can be
+#' customized using \code{\link{pmColors}}.
+#'
+#' @section Base Colors:
+#' \describe{
+#'   \item{\code{background}}{Map background color}
+#'   \item{\code{earth}}{Land/terrain color}
+#'   \item{\code{water}}{Water bodies color}
+#' }
+#'
+#' @section Land Use Colors:
+#' \describe{
+#'   \item{\code{park_a}, \code{park_b}}{Park colors (use \code{park} in pmColors)}
+#'   \item{\code{wood_a}, \code{wood_b}}{Forest/woodland colors (use \code{wood} in pmColors)}
+#'   \item{\code{hospital}}{Hospital areas}
+#'   \item{\code{industrial}}{Industrial zones}
+#'   \item{\code{school}}{Schools and universities}
+#'   \item{\code{beach}}{Beach areas}
+#'   \item{\code{zoo}}{Zoo areas}
+#'   \item{\code{aerodrome}}{Airport areas}
+#'   \item{\code{glacier}}{Glacier areas}
+#' }
+#'
+#' @section Road Colors:
+#' \describe{
+#'   \item{\code{highway}}{Highway/motorway color}
+#'   \item{\code{major}}{Major road color}
+#'   \item{\code{minor_a}, \code{minor_b}}{Minor road colors (use \code{minor} in pmColors)}
+#'   \item{\code{railway}}{Railway lines}
+#'   \item{\code{pier}}{Pier/dock structures}
+#' }
+#'
+#' @section Label Colors:
+#' \describe{
+#'   \item{\code{city_label}}{City name labels}
+#'   \item{\code{state_label}}{State/region labels}
+#'   \item{\code{country_label}}{Country name labels}
+#'   \item{\code{ocean_label}}{Ocean/sea labels}
+#'   \item{\code{roads_label_major}}{Major road name labels}
+#'   \item{\code{roads_label_minor}}{Minor road name labels}
+#' }
+#'
+#' @section Landcover Colors (optional object):
+#' These are specified as a nested object:
+#' \describe{
+#'   \item{\code{grassland}}{Grassland areas}
+#'   \item{\code{barren}}{Barren land}
+#'   \item{\code{urban_area}}{Urban zones}
+#'   \item{\code{farmland}}{Agricultural areas}
+#'   \item{\code{forest}}{Forest areas}
+#'   \item{\code{scrub}}{Scrubland}
+#' }
+#'
+#' @name protomaps_colors
+#' @seealso \code{\link{pmColors}}, \code{\link{addProtomaps}}
+NULL