Movatterモバイル変換

Title:	Customizable China and Global Map Visualizations
Version:	0.3.0
Description:	A 'ggplot2' extension centered on map visualization of China and the globe. Provides customizable projections, boundary styles, coordinate grids, scale bars, and buffer zones for thematic maps, suitable for spatial data analysis and cartographic visualization.
License:	GPL-3
Encoding:	UTF-8
Depends:	R (≥ 4.3.0), ggplot2 (≥ 3.5.0)
Imports:	sf (≥ 1.0.0), dplyr (≥ 1.1.0), terra (≥ 1.7), tidyterra (≥0.6.0), curl (≥ 5.0.0), rlang, digest, grid
URL:	https://rimagination.github.io/ggmapcn/
BugReports:	https://github.com/Rimagination/ggmapcn/issues
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-11-23 04:52:44 UTC; Administrator
Author:	Liang Ren [aut, cre]
Maintainer:	Liang Ren <rl23@mails.tsinghua.edu.cn>
Repository:	CRAN
Date/Publication:	2025-11-23 06:10:08 UTC

ggmapcn: China-Focused Mapping Tools with Optional Global Support for ggplot2

Description

**ggmapcn** provides lightweight, ready-to-use tools for drawing China andworld maps with *ggplot2*. It bundles clean geodata and offers simple,projection-aware helpers for basemaps, graticules, compasses, and scale bars.

Details

## Main Features

- **World maps**: 'geom_world()' draws a complete global basemap withcountries, coastlines, boundaries, and optional ocean fill.

- **China maps**: 'geom_mapcn()' and 'geom_boundary_cn()' provide provincial,prefecture-level maps and coastlines.

- **Annotation tools**:- 'annotation_graticule()' — global graticules with projection-aware labels.- 'annotation_scalebar()' — scale bar with automatic units and CRSdetection.- 'annotation_compass()' — north arrow with several styles.

- **Projection helper**:- 'coord_proj()' — specify geographic 'xlim'/'ylim' in degrees andautomatically transform to any projection.

- **Geodata management**:- 'check_geodata()' locates bundled world and China datasets and ensuresgraceful behaviour when data or internet resources are unavailable.

## Integration

All functions return standard *ggplot2* layers and work seamlessly with'sf' objects, custom projections, and 'coord_sf()'.

Author(s)

Maintainer: Liang Renrl23@mails.tsinghua.edu.cn (ORCID)

See Also

Useful links:

• https://rimagination.github.io/ggmapcn/

• Report bugs athttps://github.com/Rimagination/ggmapcn/issues

Add a Spatially-Aware Compass

Description

'annotation_compass()' adds a compass (north arrow) to a ggplot map.It can align to **grid north** (top of the panel) or **true north**(geographic north). Styles are provided as grobs or functions returninggrobs (for example 'north_arrow_classic()', 'compass_sinan()').

Usage

annotation_compass(  mapping = NULL,  data = NULL,  ...,  location = "bl",  which_north = "grid",  height = unit(1.5, "cm"),  width = unit(1.5, "cm"),  pad_x = unit(0.5, "cm"),  pad_y = unit(0.5, "cm"),  rotation = NULL,  style = north_arrow_classic())

Arguments

Details

* '"grid"' north: the compass points straight up in plotting space(no CRS required).* '"true"' north: the compass rotates toward the geographic North Poleusing the plot CRS. This requires a valid CRS supplied by 'coord_sf()'or injected via 'layer$geom_params$crs'.* A fixed 'rotation' (degrees counter-clockwise) always overrides theautomatic '"grid"' / '"true"' logic.* The layer is annotation-like: it draws once per panel based on thepanel bounds.

Value

A ggplot2 layer object.

See Also

[compass-styles]

Examples

nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)base <- ggplot() +  geom_sf(data = nc, fill = "grey90") +  theme_minimal()# Example 1: Grid north (no CRS required), bottom-leftbase + annotation_compass()# Example 2: Custom style & position (top-left)base + annotation_compass(location = "tl", style = compass_sinan())# Example 3: True north (requires a CRS)base +  coord_sf(crs = "+proj=lcc +lon_0=-100 +lat_1=33 +lat_2=45") +  annotation_compass(location = "br", which_north = "true")

Global graticule annotation for ggplot2 maps

Description

Draw global latitude-longitude graticules with degree labels as annotationlayers for 'ggplot2' maps. Graticules are constructed in geographiccoordinates (EPSG:4326) over a user-defined window (given by 'xlim'/'ylim',default: the full globe), optionally split at the antimeridian according tothe target CRS, and then transformed into the map CRS. Regional maps usuallydo not need this function and can rely on the default 'coord_sf()' axes.

Usage

annotation_graticule(  xlim = NULL,  ylim = NULL,  crs = "+proj=longlat +datum=WGS84",  lon_step = 60,  lat_step = 30,  line_color = "grey70",  line_width = 0.3,  line_type = "dashed",  label_color = "grey30",  label_size = 3,  label_offset = 5,  label_offset_lon = NULL,  label_offset_lat = NULL,  sides = c("left", "bottom"),  ...)

Arguments

Details

Graticules are always generated in WGS84 longitude-latitude (EPSG:4326).When a non-zero central meridian ('lon_0') is detected in the target CRS,meridians and parallels can be split at the antimeridian via'sf::st_break_antimeridian()' before being transformed, which avoidsunexpected line wrapping in projections centred away from 0 degrees.

Latitude labels at +/-90 degrees are always omitted. When drawing a full-globelongitude-latitude map with a 0 degree central meridian (that is, when 'xlim' and'ylim' are both 'NULL' and the CRS is geographic with 'lon_0 = 0'),longitude labels at +/-180 degrees are omitted (the corresponding graticule lines maystill be drawn).

Value

A list of two 'ggplot2' layers: a 'geom_sf()' layer for graticulelines and a 'geom_text()' layer for the labels.

Examples

library(ggplot2)# 1. Graticule on a WGS84 world mapggplot() +  geom_world() +  annotation_graticule(    lon_step     = 60,    lat_step     = 30,    label_offset = 5  ) +  coord_sf(crs = "+proj=longlat +datum=WGS84") +  theme_void()# 2. Robinson projection centred at 150Ecrs_robin_150 <- "+proj=robin +lon_0=150 +datum=WGS84"ggplot() +  geom_world(crs = crs_robin_150) +  annotation_graticule(    crs           = crs_robin_150,    lon_step      = 30,    lat_step      = 15,    label_offset = 3e5  ) +  coord_sf(crs = crs_robin_150) +  theme_void()# 3. Regional China map (long-lat) with graticule lines and axis labelscn_xlim <- c(70, 140)cn_ylim <- c(0, 60)ggplot() +  geom_world() +  annotation_graticule(    xlim          = cn_xlim,    ylim          = cn_ylim,    crs           = 4326,    lon_step      = 10,    lat_step      = 10,    label_color   = NA,    # draw only lines; use axis labels instead    label_offset = 1,    label_size    = 3.5  ) +  coord_sf(    xlim   = cn_xlim,    ylim   = cn_ylim,    expand = FALSE  ) +  labs(    x = "Longitude",    y = "Latitude"  ) +  theme_bw()

Add a Spatially-Aware Scale Bar

Description

'annotation_scalebar()' adds a projection-aware scale bar to a ggplot map.It reads the map's CRS (from 'coord_sf()' or from the 'crs' argument),chooses a readable width and units, and uses robust fallbacks so that thescale bar still draws even when CRS information is limited.

Supported styles:* '"segment"' – minimal horizontal bar with ticks and labels (default)* '"ticks"' – baseline with vertical ticks* '"bar"' – alternating black/white blocks

Usage

annotation_scalebar(  mapping = NULL,  data = NULL,  ...,  location = "bl",  style = "segment",  fixed_width = NULL,  crs_unit = NULL,  crs = NULL,  display_unit = NULL,  unit_labels = NULL,  width_hint = 0.25,  unit_category = "metric",  bar_cols = c("black", "white"),  line_width = 1,  height = grid::unit(0.25, "cm"),  pad_x = grid::unit(0.25, "cm"),  pad_y = grid::unit(0.25, "cm"),  text_pad = grid::unit(0.15, "cm"),  text_cex = 0.7,  text_face = NULL,  text_family = "",  tick_height = 0.6,  segments = NULL,  label_show = "ends",  minor_tick_height = 0.5,  geographic_mode = c("approx_m", "degrees"),  text_col = "black",  line_col = "black")

Arguments

Details

* With a **projected CRS** (for example UTM or AEQD in meters), the scale baris measured in native map units and is as accurate as the projection.* With a **geographic CRS** (EPSG:4326, degrees), distance depends onlatitude. The 'geographic_mode' argument controls how degrees are handled:- '"approx_m"' (default): approximate meters/kilometers using agreat-circle distance at the panel’s mid-latitude (a warning is issued).- '"degrees"': display raw degree units (for example '1°') withoutconverting.* You can override the automatically chosen width with 'fixed_width',which is interpreted in native CRS units.

Value

A ggplot2 layer representing a scale bar.

Examples

nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)base_plot <- ggplot() +  geom_sf(data = nc, fill = "grey90") +  theme_minimal()# Example 1: Projected CRS with a longer scale barbase_plot +  coord_sf(crs = 32617) +  annotation_scalebar(location = "bl", width_hint = 0.5)# Example 2: Ticks style, top-rightbase_plot +  coord_sf(crs = 32617) +  annotation_scalebar(location = "tr", style = "ticks")# Example 3: Geographic CRS (EPSG:4326), approximate meters (warns)base_plot +  coord_sf(crs = 4326) +  annotation_scalebar(location = "bl", geographic_mode = "approx_m")# Example 4: Force a 100 km bar with red outlinesbase_plot +  coord_sf(crs = 32617) +  annotation_scalebar(    location     = "bl",    fixed_width  = 100000,    display_unit = "km",    line_col     = "red"  )

Elevation Map of China Layer for ggplot2

Description

'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 areaaround China. Users can provide their own DEM data using the 'data' parameter, or the defaultbuilt-in DEM data will be used.

Usage

basemap_dem(  data = NULL,  crs = NULL,  within_china = FALSE,  maxcell = 1e+06,  na.rm = FALSE,  ...)

Arguments

Value

A 'ggplot' object containing the elevation map of China as a layer, which can be further customized or plotted.

See Also

geom_boundary_cn

Examples

# Before using the basemap_dem function, make sure the required data files are available.# The required files are: "gebco_2024_China.tif" and "China_mask.gpkg".# You can use check_geodata() to download them from GitHub if they are not available locally.# Check and download the required data files if they are missingcheck_geodata(files = c("gebco_2024_China.tif", "China_mask.gpkg"))# Define the CRS for China (EPSG:4326 is a common global geographic coordinate system)china_proj <- "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs"# Example 1: Display full rectangular area around China using built-in DEM dataggplot() +  basemap_dem(within_china = FALSE) +  tidyterra::scale_fill_hypso_tint_c(    palette = "gmt_globe",    breaks = c(-10000, -5000, 0, 2000, 5000, 8000)  ) +  theme_minimal()# Example 2: Display only China's DEM and boundaries using built-in DEM dataggplot() +  basemap_dem(crs = china_proj, within_china = TRUE) +  geom_boundary_cn(crs = china_proj) +  tidyterra::scale_fill_hypso_c(    palette = "dem_print",    breaks = c(0, 2000, 4000, 6000),    limits = c(0, 7000)  ) +  labs(fill = "Elevation (m)") +  theme_minimal()

Vegetation Map of China Layer for ggplot2

Description

Adds a vegetation raster map of China to a ggplot2 plot, with color-coded vegetation types.

Usage

basemap_vege(  color_table = NULL,  crs = NULL,  maxcell = 1e+06,  use_coltab = TRUE,  na.rm = FALSE,  ...)

Arguments

Value

A ggplot2 layer object representing the vegetation map of China.

References

Zhang X, Sun S, Yong S, et al. (2007). *Vegetation map of the People's Republic of China (1:1000000)*. Geology Publishing House, Beijing.

Examples

# Example1: Check and load the vegetation raster map# Make sure the required raster data is availablecheck_geodata(files = c("vege_1km_projected.tif"))# Once the data is checked or downloaded, add the vegetation raster to a ggplotggplot() +  basemap_vege() +  theme_minimal()# Example2: Customize color tablecustom_colors <- data.frame(  code = 0:11,  type = c(    "Non-vegetated", "Needleleaf forest", "Needleleaf and broadleaf mixed forest",    "Broadleaf forest", "Scrub", "Desert", "Steppe", "Grassland",    "Meadow", "Swamp", "Alpine vegetation", "Cultivated vegetation"  ),  col = c(    "#8D99B3", "#97B555", "#34BF36", "#9ACE30", "#2EC6C9", "#E5CE0E",    "#5BB1ED", "#6494EF", "#7AB9CB", "#D97A80", "#B87701", "#FEB780"  ))ggplot() +  basemap_vege(color_table = custom_colors) +  labs(fill = "Vegetation type group") +  theme_minimal()

Check and retrieve required geodata files

Description

Ensures that external geospatial data files required byggmapcn areavailable locally. Existing files are reused whenoverwrite = FALSE;missing files are downloaded from remote mirrors when possible. If allmirrors fail (for example, due to network restrictions), the function failsgracefully by returningNA for the affected files without raisingwarnings or errors, in line with CRAN policy.

Usage

check_geodata(  files = NULL,  overwrite = FALSE,  quiet = FALSE,  max_retries = 3,  mirrors = NULL,  use_checksum = TRUE,  checksums = NULL,  resume = TRUE,  local_dirs = NULL)

Arguments

Details

Because CRAN enforces strict limits on package size, several large datasetsare hosted externally rather than bundled in the package.check_geodata()locates or retrieves these files using the following priority:

1. user-specifiedlocal_dirs

2. the packageextdata directory

3. the per-user cache directory viatools::R_user_dir("ggmapcn", "data")

High-level mapping functions such asgeom_mapcn() andgeom_world()callcheck_geodata() internally, so most users do not need to invoke itdirectly. However, running it explicitly can be useful to pre-fetch or verifyrequired files.

On networks that cannot reliably accesscdn.jsdelivr.net orraw.githubusercontent.com, downloads may time out and the correspondingentries in the returned vector will beNA. In such cases, users maymanually download the required files from the data repository and place theminto a directory supplied throughlocal_dirs, the packageextdatadirectory, or the user cache directory so that downloads are skipped.

Note: recent versions ofgeom_world() use the following world datasets:world_countries.rda,world_coastlines.rda, andworld_boundaries.rda. The legacyworld.rda file is no longerused.

Value

A character vector of absolute file paths. Any file that cannot be obtainedis returned asNA.

Examples

# Ensure that all default datasets are available (downloads only if needed)check_geodata()# Datasets used by geom_world()check_geodata(c(  "world_countries.rda",  "world_coastlines.rda",  "world_boundaries.rda"))# China administrative boundariescheck_geodata(c("China_sheng.rda", "China_shi.rda", "China_xian.rda"))# Reuse files manually placed in the working directorycheck_geodata("world_countries.rda", local_dirs = getwd())

Coordinate System with Geographic Limits Automatically Transformed to a Projection

Description

'coord_proj()' extends [ggplot2::coord_sf()] by allowing users to specifymap limits ('xlim', 'ylim') in geographic coordinates (longitude/latitude, WGS84).These limits are automatically transformed into the target projected CRS,ensuring that maps display the intended region correctly under any projection.

Usage

coord_proj(  crs = NULL,  xlim = NULL,  ylim = NULL,  expand = TRUE,  default_crs = "EPSG:4326",  ...)

Arguments

Details

This wrapper is particularly useful because [ggplot2::coord_sf()] interprets'xlim' and 'ylim' as *projected* coordinates (in the units of the target CRS).Passing longitude/latitude directly to 'coord_sf()' results in incorrect mapextents unless the output CRS is also WGS84.

'coord_proj()' provides a safe, projection-aware workflow that calculatesthe bounding box in WGS84, transforms it to the target CRS, and passes thenew limits to 'coord_sf()'.

Value

A 'CoordSf' object (specifically a result of 'coord_sf()') withautomatically transformed limits.

See Also

* [ggplot2::coord_sf()] for the underlying function.* [geom_world()] for the basemap layer.

Examples

library(ggplot2)# Example 1: China (AEQD projection) with geographic limitschina_proj <- "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs"ggplot() +  geom_world(crs = china_proj) +  coord_proj(    crs = china_proj,    xlim = c(60, 140),    ylim = c(-10, 50)  ) +  theme_minimal()# Example 2: Zooming into a specific region# Even though the map is projected (Robinson), we specify limits in Lat/Loncrs_robin <- "+proj=robin +lon_0=0 +datum=WGS84"ggplot() +  geom_world(crs = crs_robin) +  coord_proj(    crs = crs_robin,    xlim = c(-20, 50), # Focus on Africa/Europe    ylim = c(-40, 40)  ) +  theme_minimal()

Plot Boundaries of China

Description

Draw China's administrative boundaries and optional map decorations(compass and scale bar). Each boundary category (mainland, coastline,provinces, etc.) can be styled independently. The boundary data arereprojected to the specified CRS before plotting.

Usage

geom_boundary_cn(  crs = "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs",  compass = FALSE,  scale = FALSE,  mainland_color = "black",  mainland_size = 0.2,  mainland_linetype = "solid",  coastline_color = "blue",  coastline_size = 0.1,  coastline_linetype = "solid",  ten_segment_line_color = "black",  ten_segment_line_size = 0.2,  ten_segment_line_linetype = "solid",  SAR_boundary_color = "grey40",  SAR_boundary_size = 0.1,  SAR_boundary_linetype = "dashed",  undefined_boundary_color = "black",  undefined_boundary_size = 0.2,  undefined_boundary_linetype = "dotdash",  province_color = "transparent",  province_size = 0.1,  province_linetype = "solid",  ...)

Arguments

Value

A list of 'ggplot2' layers. If the boundary dataset cannot beobtained, an empty list is returned.

Examples

# Example 1: Basic China mapggplot() +  geom_boundary_cn() +  theme_minimal()# Example 2: Add compass and scale bar (easy mode)ggplot() +  geom_boundary_cn(compass = TRUE, scale = TRUE) +  theme_minimal()# Example 3: Custom stylingggplot() +  geom_boundary_cn(    coastline_color  = "steelblue",    province_color   = "grey70",    province_linetype = "dashed"  ) +  theme_minimal()# Example 4: Advanced usage with a custom projected CRS (Albers)albers_cn <- "+proj=aea +lat_1=25 +lat_2=47 +lat_0=0 +lon_0=105 +datum=WGS84 +units=m +no_defs"ggplot() +  geom_boundary_cn(crs = albers_cn) +  annotation_compass(location = "tl", which_north = "true") +  annotation_scalebar(location = "bl", fixed_width = 500000, display_unit = "km") +  coord_sf(crs = albers_cn) +  theme_minimal()

Plot Buffered Layers for China's Boundary

Description

Creates a ggplot2 layer for displaying buffered areas around China's boundaries,including both the mainland boundary and the ten-segment line. Buffers with user-defined distancesare generated around each boundary, providing flexibility in projection and appearance.

Usage

geom_buffer_cn(  mainland_dist = 20000,  ten_line_dist = NULL,  crs = "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs",  color = NA,  fill = "#D2D5EB",  ...)

Arguments

Value

A ggplot2 layer displaying buffered areas around China's boundaries,with customizable buffer distances for the mainland boundary and the ten-segment line,using the specified projection.

Examples

# Plot buffers with specified distances for mainland and ten-segment lineggplot() +  geom_buffer_cn(    mainland_dist = 10000,    ten_line_dist = 5000  ) +  theme_minimal()

Visualize Spatial Point Data

Description

'geom_loc' is a wrapper aroundggplot2::geom_sf() designedfor visualizing spatial point data. It supports bothsf objects and tabular data frameswith longitude and latitude columns, automatically transforming them into the specifiedcoordinate reference system (CRS).

Usage

geom_loc(  data,  lon = NULL,  lat = NULL,  crs = "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs",  mapping = ggplot2::aes(),  ...)

Arguments

Details

This function simplifies the process of visualizing spatial data in ggplot2 by automaticallyhandling CRS transformations and providing an interface for bothsf and tabular data.If the input is a tabular data frame, it will be converted to ansf object using thespecified longitude and latitude columns.

Seeggplot2::geom_sf() for details on additional parametersand aesthetics.

Value

A ggplot2 layer for visualizing spatial point data, either from an 'sf' object or a tabular data framewith longitude and latitude columns, after transforming the data to the specified coordinate reference system (CRS).

See Also

geom_boundary_cn

Examples

# Generate a random dataset with latitude and longitudeset.seed(123)data_sim <- data.frame(  Longitude = runif(100, 80, 120),  Latitude = runif(100, 28, 40),  Category = sample(c("Type A", "Type B", "Type C"), 100, replace = TRUE))# Visualize the data with China's boundariesggplot() +  geom_boundary_cn() +  geom_loc(    data = data_sim, lon = "Longitude", lat = "Latitude",    mapping = aes(color = Category), size = 1, alpha = 0.7  ) +  theme_minimal()

Plot China Map with Customizable Options

Description

‘geom_mapcn()' draws China’s administrative units with a simple, opinionatedinterface. When 'data' is 'NULL', it loads packaged map data for the requestedadministrative level, optionally applies attribute-based filtering, removesinternal clipping rows, and reprojects the layer to the target CRS.

In typical use, 'geom_mapcn()' is combined with 'geom_boundary_cn()' to drawcoastlines, national borders, and other boundary features on top of theadministrative polygons.

Usage

geom_mapcn(  data = NULL,  admin_level = "province",  crs = "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs",  color = "black",  fill = "white",  linewidth = 0.1,  filter_attribute = NULL,  filter = NULL,  mapping = NULL,  ...)

Arguments

Details

If 'data' is 'NULL', 'geom_mapcn()' selects one of the packaged datasets:

* 'admin_level = "province"' → 'China_sheng.rda'* 'admin_level = "city"' → 'China_shi.rda'* 'admin_level = "county"' → 'China_xian.rda'

The file is ensured to exist locally via 'check_geodata()', which may reusean existing copy in the package 'extdata' directory or user cache, or downloadit from the external repository when necessary. The '.rda' file is thenloaded from the resolved path, and the main 'sf' object is extracted.

A special row labelled '"Boundary Line"' (used for technical clipping) isremoved automatically when present. Attribute-based filtering can be appliedusing 'filter_attribute' and 'filter' before reprojecting to the target CRS.

Value

A 'ggplot2' layer that can be added to a plot.

Examples

# 1. Basic provincial map (recommended: combine with geom_boundary_cn)ggplot() +  geom_mapcn() +  geom_boundary_cn() +  theme_minimal()# 2. City-level map with custom fill and boundariesggplot() +  geom_mapcn(    admin_level = "city",    fill = "grey95",    color = "grey60"  ) +  geom_boundary_cn(province_color = "grey40") +  theme_bw()# 3. Filter by attribute (e.g., English names) and highlight selected provincesggplot() +  geom_mapcn(    filter_attribute = "name_en",    filter = c("Beijing", "Shanghai"),    fill = "tomato"  ) +  geom_boundary_cn() +  theme_minimal()# 4. Use a different projection (e.g., Albers equal-area)albers_cn <- "+proj=aea +lat_1=25 +lat_2=47 +lat_0=0 +lon_0=105 +datum=WGS84"ggplot() +  geom_mapcn(crs = albers_cn, linewidth = 0.3) +  geom_boundary_cn(crs = albers_cn) +  coord_sf(crs = albers_cn) +  theme_minimal()

Convenient Global Basemap Layer for ggplot2

Description

'geom_world()' draws a styled global basemap using bundled countrypolygons, coastlines, and administrative boundary data. It automaticallyhandles antimeridian splitting and CRS transformation, and supportsoptional country filtering for focused maps.

Usage

geom_world(  crs = 4326,  filter_attribute = "SOC",  filter = NULL,  show_ocean = TRUE,  show_admin_boundaries = TRUE,  show_frame = FALSE,  ocean_fill = "#c7e8fb",  frame_color = "black",  frame_size = 0.2,  frame_linetype = "solid",  country_fill = "grey90",  country_boundary_color = "transparent",  country_boundary_size = 0.1,  country_boundary_linetype = "solid",  coastline_color = "#26ace7",  coastline_size = 0.1,  coastline_linetype = "solid",  international_boundary_color = "grey20",  international_boundary_size = 0.1,  international_boundary_linetype = "solid",  regional_boundary_color = "grey20",  regional_boundary_size = 0.1,  regional_boundary_linetype = "dashed",  undefined_boundary_color = "grey20",  undefined_boundary_size = 0.1,  undefined_boundary_linetype = "longdash",  military_boundary_color = "grey20",  military_boundary_size = 0.1,  military_boundary_linetype = "dotted",  ...)

Arguments

Details

This function supersedes early development versions that required users tosupply their own map data.

The current implementation:

- Always uses bundled world map data (countries, coastlines, boundaries).- Exposes dedicated arguments for ocean fill, coastlines, and administrative boundaries.- Builds a projection-aware global outline for the ocean/frame layer.For **geographic CRSs** (including those with a shifted central meridian,e.g., '+lon_0=150'), it creates a seamless rectangular bounding box directlyin the target CRS to avoid topological splitting artifacts (vertical lines).For **projected CRSs** (e.g., Robinson, Mollweide), it computes the convexhull of the projected graticule.

Value

A list of [ggplot2] layers representing the world map (or afiltered subset), ready to be added to a ggplot.

Examples

library(ggplot2)# 1. Simple World Map (WGS84)ggplot() +  geom_world() +  theme_void()# 2. Pacific-Centered View (Shifted LongLat)crs_longlat_150 <- "+proj=longlat +datum=WGS84 +lon_0=150"ggplot() +  geom_world(crs = crs_longlat_150, show_frame = TRUE, show_ocean = FALSE) +  theme_void()# 3. Robinson Projection (Projected CRS)crs_robin <- "+proj=robin +lon_0=0 +datum=WGS84"ggplot() +  geom_world(crs = crs_robin, show_frame = TRUE) +  theme_void()# 4. Without administrative boundariesggplot() +  geom_world(show_admin_boundaries = FALSE) +  theme_minimal()# 5. Highlighting specific countries (China)ggplot() +  geom_world(country_fill = "grey95") +  geom_world(    filter_attribute = "SOC",    filter = "CHN",    country_fill = "red",    country_boundary_color = "black"  ) +  theme_void()

Classic North Arrow Style (Minimal)

Description

A collection of style constructors that return 'grid' grobs for use with'annotation_compass(style = ...)'. These styles provide different visualappearances for a compass or north arrow drawn as an annotation.

Usage

north_arrow_classic(  fill = c("white", "black"),  line_col = "black",  line_width = 2,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")compass_sinan(  line_col = "black",  square_pad = 0.1,  ring_outer = 0.35,  ring_ratio = 0.65,  labels = c("N", "E", "S", "W"),  text_size = 12,  text_face = "plain",  text_family = "",  text_col = "black",  label_offset = 0.05,  spoon_fill = "black",  spoon_col = "black",  spoon_scale = 0.8,  inner_fill = "lightgrey",  square_width = 2,  outer_width = 2,  inner_width = 1,  spoon_width = 1)north_arrow_classic(  fill = c("white", "black"),  line_col = "black",  line_width = 2,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")north_arrow_solid(  fill = "black",  line_col = "black",  line_width = 1,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")compass_rose_simple(  fill = c("white", "black"),  line_col = "black",  line_width = 1,  sharpness = 0.7,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")compass_rose_classic(  fill = c("white", "black"),  line_col = "black",  line_width = 1.5,  sharpness = 0.6,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")compass_rose_circle(  fill = "white",  line_col = "black",  line_width = 3,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")compass_guiding_fish(  size = 1,  ring_ratio = 0.2,  ring_width = 2,  n_seg = 16,  fish_col = "black",  fish_shift = -0.03,  text_col = "black",  text_size = 12,  text_face = "plain",  text_family = "")compass_sinan(  line_col = "black",  square_pad = 0.1,  ring_outer = 0.35,  ring_ratio = 0.65,  labels = c("N", "E", "S", "W"),  text_size = 12,  text_face = "plain",  text_family = "",  text_col = "black",  label_offset = 0.05,  spoon_fill = "black",  spoon_col = "black",  spoon_scale = 0.8,  inner_fill = "lightgrey",  square_width = 2,  outer_width = 2,  inner_width = 1,  spoon_width = 1)

Arguments

Details

Exported constructors documented under this topic:

• north_arrow_classic()

• north_arrow_solid()

• compass_rose_simple()

• compass_rose_classic()

• compass_rose_circle()

• compass_guiding_fish()

• compass_sinan()

Each constructor returns a grob ready to be passed toannotation_compass(style = ...).All styles include an "N" (or cardinal labels) to indicate north.

Value

A 'grid' graphical object (grob).

See Also

[annotation_compass] for adding the compass to a ggplot.

Examples

# Standalone previewgrid::grid.newpage(); grid::grid.draw(north_arrow_classic())grid::grid.newpage(); grid::grid.draw(north_arrow_solid())grid::grid.newpage(); grid::grid.draw(compass_rose_simple())grid::grid.newpage(); grid::grid.draw(compass_rose_classic())grid::grid.newpage(); grid::grid.draw(compass_rose_circle())grid::grid.newpage(); grid::grid.draw(compass_guiding_fish())grid::grid.newpage(); grid::grid.draw(compass_sinan())# Use in ggplotif (requireNamespace("ggplot2", quietly = TRUE) &&    requireNamespace("sf", quietly = TRUE)) {  nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)  p <- ggplot2::ggplot() +    ggplot2::geom_sf(data = nc, fill = "grey90") +    ggplot2::theme_minimal()  p + annotation_compass(location = "tr", style = north_arrow_classic())  p + annotation_compass(location = "bl", style = compass_sinan())}