---
title: "viewscape"
author: "Xiaohao Yang"
date: "2024-06-06"
vignette: >
  %\VignetteIndexEntry{viewscape}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
# Viewscape

This vignette provides a basic overview of the functions in R package `viewscape`.

The basic viewshed analysis can be accessed through calling the `compute_viewshed`. The two needed objects to compute the viewshed are a digital surface model (DSM) and a viewpoint.

## 1. Compute viewshed

```{r eval=FALSE}
library(viewscape)
```

### 1.1 Compute single viewshed

```{r eval=FALSE}
#Load in DSM
test_dsm <- terra::rast(system.file("test_dsm.tif", 
                                       package ="viewscape"))

#Load in the viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", 
                                          package = "viewscape"))

#Compute viewshed
output <- viewscape::compute_viewshed(dsm = test_dsm, 
                                      viewpoints = test_viewpoint, 
                                      offset_viewpoint = 6, 
                                      r = 1600,
                                      method = 'plane')
```

```{r eval=FALSE}
# overlap viewshed on DSM
output_r <- viewscape::visualize_viewshed(output, outputtype = 'raster')
terra::plot(test_dsm, axes=FALSE, box=FALSE, legend = FALSE)
terra::plot(output_r, add=TRUE, col = "red", axes=FALSE, box=FALSE, legend = FALSE)
terra::plot(test_viewpoint, add = TRUE, col = "blue", axes=FALSE, box=FALSE, legend = FALSE)
```

### 1.2 Subset viewshed using by specifying the field of view

```{r eval=FALSE}
sector <- viewscape::fov_mask(output, c(40,160))
terra::plot(test_dsm, axes=FALSE, box=FALSE, legend = FALSE)
terra::plot(viewscape::visualize_viewshed(sector, outputtype = 'raster'),
            axes=FALSE, box=FALSE, legend = FALSE, add = TRUE, col = "red")
terra::plot(test_viewpoint, add = TRUE, col = "blue", axes=FALSE, box=FALSE, legend = FALSE)
```

### 1.3 Compute visual magnitude

```{r eval=FALSE}
vm <- viewscape::visual_magnitude(output,test_dsm)
terra::plot(vm, axes=FALSE, box=FALSE)
terra::plot(test_viewpoint, add = TRUE, col = "blue", axes=FALSE, box=FALSE, legend = FALSE)
```


### 1.4 Compute the viewshed for multiple viewpoints

```{r eval=FALSE}
#Load in DSM
test_dsm <- terra::rast(system.file("test_dsm.tif", 
                                       package ="viewscape"))

# Load points (.shp file)
test_viewpoints <- sf::read_sf(system.file("test_viewpoints.shp", 
                                           package = "viewscape"))

# Compute viewsheds
output <- viewscape::compute_viewshed(dsm = test_dsm, 
                                      viewpoints = test_viewpoints, 
                                      offset_viewpoint = 6, 
                                      parallel = TRUE, 
                                      workers = 1)
```

```{r eval = FALSE}
# Use plot all viewsheds on DSM
par(mfrow=c(3,3))
for(i in 1:length(output)) {
  each <- output[[i]]
  raster_data <- viewscape::visualize_viewshed(each, outputtype="raster")
  terra::plot(test_dsm, axes=FALSE, box=FALSE, legend = FALSE)
  terra::plot(raster_data, add=TRUE, col = "red", axes=FALSE, box=FALSE, legend = FALSE)
}
```

## 2. Calculate viewscape metrics

### 2.1 Calculate the metrics of viewshed
The function of view depth analysis can calculate two different metrics: the furthest distance and standard deviation of distances. To calculate view depth, there are two needed objects: the DSM that was used to get viewshed and result from viewshed analysis.

The function of extent analysis can calculate the total area of viewshed and needs the DSM that was used to get viewshed and result from viewshed analysis. 

The following function can calculate the area of ground surface and standard deviation of elevations within a viewshed. The function needs a DSM and a DEM/DTM to calculate the metrics.

```{r eval=FALSE}
#Load in DSM
test_dsm <- terra::rast(system.file("test_dsm.tif", 
                                       package ="viewscape"))
# Load DTM
test_dtm <- terra::rast(system.file("test_dtm.tif", 
                                       package ="viewscape"))

# Load canopy raster
test_canopy <- terra::rast(system.file("test_canopy.tif", 
                                       package ="viewscape"))

# Load building footprints raster
test_building <- terra::rast(system.file("test_building.tif", 
                                       package ="viewscape"))

```

```{r eval=FALSE}
# calculate metrics given the viewshed, canopy, and building footprints
test_metrics <- viewscape::calculate_viewmetrics(output[[1]], 
                                                 test_dsm, 
                                                 test_dtm, 
                                                 list(test_canopy, test_building))
test_metrics
```

### 2.2 Calculate land use/cover diversity

calculate_diversity() calculates the proportion of each type of land use/ cover within a viewshed to get the Shannon Diversity Index. 

```{r eval=FALSE}
# load landuse raster
test_landuse <- terra::rast(system.file("test_landuse.tif",
                                        package ="viewscape"))
```

```{r eval=FALSE}
# the Shannon Diversity Index (SDI)
test_diversity <- viewscape::calculate_diversity(output[[1]],
                                                 test_landuse,
                                                 proportion = TRUE)
# SDI and The proportion of each type of land use
test_diversity
```

### 2.3 calculate a single feature

calculate_feature is to calculate the proportion of a feature (including trees, buildings, parking, and roads) within the viewshed. This function can be applied to 

```{r eval=FALSE}
# load canopy raster
test_canopy <- terra::rast(system.file("test_canopy.tif",
                                          package ="viewscape"))
# calculate the percentage of canopy coverage  
test_canopy_proportion <- viewscape::calculate_feature(viewshed = output[[1]], 
                                                       feature = test_canopy,
                                                       type = 2,
                                                       exclude_value=0)
test_canopy_proportion
```