# viewscape

#### Xiaohao Yang

#### 2024-06-06

# 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

    library(viewscape)

### 1.1 Compute single viewshed

    #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')

    # 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

    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

    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

    #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)

    # 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.

    #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"))

    # 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.

    # load landuse raster
    test_landuse <- terra::rast(system.file("test_landuse.tif",
                                            package ="viewscape"))

    # 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

    # 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