---
title: "Adding_Spatial_Data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Adding_Spatial_Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(ggmapcn)
# Define Azimuthal Equidistant projection centered on China
china_proj <- "+proj=aeqd +lat_0=35 +lon_0=105 +ellps=WGS84 +units=m +no_defs"
```

## Introduction

This vignette introduces two functions in the ggmapcn package: `geom_loc` and `geom_vege_raster`. These functions extend the capabilities of the package for spatial data visualization.

## geom_loc: Adding Spatial Point Data Layer with Color by Grouping

The `geom_loc` function allows you to add spatial point data to a ggplot, supporting both sf and tabular data frames, with color mapping based on a grouping variable.

```{r geom_loc, fig.alt='Sample site'}
# Create a ggplot with spatial points colored by 'Category'
set.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)
   )
ggplot() +
   geom_boundary_cn() +
   geom_loc(
     data = data_sim, lon = "Longitude", lat = "Latitude",
     mapping = aes(color = Category), size = 1, alpha = 0.7
   ) +
   theme_bw()
```

## basemap_vege: Vegetation Map of China Layer for ggplot2

The `basemap_vege` function adds a vegetation raster map of China with color-coded vegetation types to a ggplot.

```{r vegetion map, fig.alt='Vegetation Map of China'}
# Add vegetation raster of China to a ggplot
ggplot() +
  basemap_vege() +
  guides(fill = guide_none()) +
  theme_bw()
```

## basemap_dem: Elevation Map of China Layer for ggplot2

The `basemap_dem` function adds a digital elevation model (DEM) raster map of China as a layer to ggplot2.

```{r dem map, fig.alt='Elevation Map of China'}
# Apply Azimuthal Equidistant projection centered on China
ggplot() +
  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() +
  theme(legend.position = "bottom")
```

## coord_proj: Transforming Limits for Custom Projections

The `coord_proj` function is a wrapper around coord_sf that allows you to specify map limits (xlim, ylim) in longitude and latitude (WGS84 CRS) and automatically transforms them into the specified CRS for accurate projections.

Here, the Azimuthal Equidistant projection centered on China is applied, with transformed map limits specified in longitude and latitude.

```{r clip region, fig.alt='clip region'}
# World map with Azimuthal Equidistant projection centered on China
ggplot() +
  geom_world(fill = "lightblue") +
  coord_proj(
    crs = china_proj,
    xlim = c(60, 140),
    ylim = c(10, 50)
  ) +
  theme_minimal()

```

Additionally, we can focus the map on the South China Sea Islands. The longitude and latitude range shown here is for demonstration purposes only.

```{r Nanhai, fig.alt='Naihai'}
ggplot() +
  geom_boundary_cn() +
  theme_bw() +
  coord_proj(
    crs = china_proj,
    expand = FALSE,
    xlim = c(105, 126),
    ylim = c(2, 23)
  )
```