Package {viewscape}

An S4 class to represent the viewshed

Description

A viewshed object contains a 'matrix' of visible and invisible area, resolution, extent, and crs

Slots

visible

matrix

resolution

vector

extent

numeric

crs

character

calculate_diversity

Description

The calculate_diversity function is designed to calculate landscape diversity metrics within a viewshed. It takes as input a land cover raster, a viewshed object representing the observer's line of sight, and an optional parameter to compute class proportions.

Usage

calculate_diversity(viewshed, land, proportion = FALSE)

Arguments

Value

List. a list containing the Shannon Diversity Index (SDI) and, if the proportion parameter is set to TRUE, a table of class proportions within the viewshed.

Examples

library(viewscape)
# Load a viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# load dsm raster
dsm <- terra::rast(system.file("test_dsm.tif", package ="viewscape"))
#Compute viewshed
output <- viewscape::compute_viewshed(dsm = dsm,
                                      viewpoints = test_viewpoint,
                                      offset_viewpoint = 6, r = 1600)
# load landuse raster
test_landuse <- terra::rast(system.file("test_landuse.tif",
                                        package ="viewscape"))
diversity <- viewscape::calculate_diversity(output,
                                            test_landuse)

calculate_feature

Description

The calculate_feature function is designed to extract specific feature-related information within a viewshed. It allows you to compute the proportion of the feature that is present in the viewshed.

Usage

calculate_feature(viewshed, feature, type, exclude_value)

Arguments

Value

Numeric. The canopy area in the viewshed.

Examples

library(viewscape)
# Load a viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# load dsm raster
dsm <- terra::rast(system.file("test_dsm.tif", package ="viewscape"))
#Compute viewshed
viewshed <- viewscape::compute_viewshed(dsm = dsm,
                                        viewpoints = test_viewpoint,
                                        offset_viewpoint = 6)
# 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 = viewshed,
                                                       feature = test_canopy,
                                                       type = 2,
                                                       exclude_value = 0)

calculate_viewmetrics

Description

The calculate_viewmetrics function is designed to compute a set of configuration metrics based on a given viewshed object and optionally, digital surface models (DSM) and digital terrain models (DTM) for terrain analysis. The function calculates various metrics that describe the visibility characteristics of a landscape from a specific viewpoint.The metrics include:

1. Extent: The total area of the viewshed, calculated as the number of visible grid cells multiplied by the grid resolution

2. Depth: The furthest visible distance within the viewshed from the viewpoint

3. Vdepth: The standard deviation of distances to visible points, providing a measure of the variation in visible distances

4. Horizontal: The total visible horizontal or terrestrial area within the viewshed

5. Relief: The standard deviation of elevations of the visible ground surface

6. Sky View Factor (SVF): The proportion of visible sky hemisphere at the viewpoint, computed by casting rays in 36 azimuth directions and calculating SVF = mean(cos^2(max obstruction angle)). Ranges from 0 (fully enclosed) to 1 (open sky).

7. Skyline: The standard deviation of the vertical viewscape, including visible canopy and buildings, when specified

8. Number of patches: Visible fragmentation measured by total visible patches with the viewscape

9. Mean shape index: Visible patchiness based on average perimeter-to-area ratio for all viewscape patches (vegetation and building)

10. Edge density: A measure of visible complexity based on the length of patch edges per unit area

11. Patch size: Total average size of a patches over the entire viewscape area

12. Patch density: Visible landscape granularity based on measuring patch density

13. Shannon diversity index: The abundance and evenness of land cover/use in a viewshed

14. Proportion of object: Proportion of a single type of land use or cover in a viewshed

Usage

calculate_viewmetrics(viewshed, dsm, dtm, masks = list())

Arguments

Value

List

References

Tabrizian, P., Baran, P.K., Berkel, D.B., Mitásová, H., & Meentemeyer, R.K. (2020). Modeling restorative potential of urban environments by coupling viewscape analysis of lidar data with experiments in immersive virtual environments. Landscape and Urban Planning, 195, 103704.

Dorman, M., Vulkan, A., Erell, E., & Kloog, I. (2019). shadow: Geometric Shadow Calculations. The R Journal, 11(1), 287–309. https://github.com/michaeldorman/shadow

Oke, T. R. (1981). Canyon geometry and the nocturnal urban heat island: comparison of scale model and field observations. Journal of Climatology, 1(3), 237–254.

Examples

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

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

# calculate metrics given the viewshed, canopy, and building footprints
test_metrics <- viewscape::calculate_viewmetrics(output,
                                                 test_dsm,
                                                 test_dtm,
                                                 list(test_canopy, test_building))

compute_viewshed

Description

The compute_viewshed function is designed for computing viewsheds, which are areas visible from specific viewpoints, based on a Digital Surface Model (DSM). It provides flexibility for single or multi-viewpoint analyses and allows options for parallel processing, raster output, and plotting.

Usage

compute_viewshed(
  dsm,
  viewpoints,
  offset_viewpoint = 1.7,
  offset_height = 0,
  r = NULL,
  refraction_factor = 0.13,
  method = "plane",
  parallel = FALSE,
  workers = 1,
  raster = FALSE,
  plot = FALSE
)

Arguments

Value

Raster or list. For single-viewpoint analysis, the function returns either a raster (raster is TRUE) or a viewshed object. Value 1 means visible while value 0 means invisible. For multi-viewpoint analysis, a list of viewsheds is returned.

Examples

# Load a viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# load dsm raster
dsm <- terra::rast(system.file("test_dsm.tif", package ="viewscape"))
#Compute viewshed
output <- viewscape::compute_viewshed(dsm = dsm,
                                      viewpoints = test_viewpoint,
                                      offset_viewpoint = 6, r = 1600)

fov_mask

Description

The fov_mask function is designed to subset a viewshed based on its viewpoint and the field of view

Usage

fov_mask(viewshed, fov)

Arguments

Details

Angles are measured clockwise from north, ranging from -180 (exclusive) to 180 (inclusive). The two angles may be given in either order. When fov[1] < fov[2] the sector spans clockwise from fov[1] to fov[2]. When fov[1] > fov[2] the sector wraps around ±180 (south) — for example c(135, -135) captures a 90° south-facing arc.

Here, 'v' represents the viewpoint. North is 0°, east is 90°, west is -90°, south is ±180°.

Value

viewshed object

See Also

compute_viewshed()

Examples

# Load a viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# load dsm raster
dsm <- terra::rast(system.file("test_dsm.tif", package ="viewscape"))
# Compute viewshed
viewshed <- viewscape::compute_viewshed(dsm,
                                        viewpoints = test_viewpoint,
                                        offset_viewpoint = 6)
# subset viewshed using the field of view (north-facing 120° arc)
out <- viewscape::fov_mask(viewshed, c(-60, 60))

intervis_network

Description

Computes an intervisibility network among a set of viewpoints, determining which pairs of viewpoints have a direct line of sight to each other. Results can be returned as a binary adjacency matrix or as an sf collection of lines suitable for mapping the network.

Usage

intervis_network(
  viewpoints,
  dsm,
  offset_viewpoint = 1.7,
  r = NULL,
  refraction_factor = 0.13,
  method = "plane",
  output = "matrix"
)

Arguments

Value

An N x N integer matrix (output = "matrix") or an sf data frame of lines (output = "lines").

See Also

compute_viewshed() fov_mask()

Examples

library(viewscape)
# Load viewpoints
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# Load DSM
dsm <- terra::rast(system.file("test_dsm.tif", package = "viewscape"))
# Compute intervisibility matrix
mat <- intervis_network(test_viewpoint, dsm, offset_viewpoint = 1.7)
# Compute intervisibility as lines
net <- intervis_network(test_viewpoint, dsm, offset_viewpoint = 1.7,
                        output = "lines")

pano_view

Description

Generate an equirectangular or cylindrical panoramic view from a DSM.

For method = "equirectangular":

• No semantic: automatically downloads ESRI WorldImagery tiles via greenSD and projects the satellite RGB colours onto the panoramic rays, producing a 3-band colour panorama (R, G, B, 0–255).

• With semantic: projects the supplied land-use / land-cover raster onto the panoramic rays, returning a 2-layer SpatRaster (depth + land-cover codes).

For method = "cylindrical" the function always returns a single-layer distance panorama (with an optional second semantic layer).

Usage

pano_view(
  dsm = NULL,
  vpt = NULL,
  h = 6,
  semantic = NULL,
  method = "equirectangular",
  sky_threshold = 3,
  step_size = 0.5,
  max_dist = 500,
  pano_dim = c(256, 512),
  ares = 0.0174533,
  heading = 0,
  color_source = NULL,
  sky_color = c(135, 206, 235),
  satellite_zoom = 17L,
  plot = FALSE,
  legend = TRUE,
  axes = TRUE
)

Arguments

Details

For heading:

• heading = 0 → facing north (default)

• heading = 90 → facing east

• heading = 180 → facing south

• heading = 270 → facing west

The equirectangular colour panorama requires the greenSD package (install with devtools::install_github("billbillbilly/greenSD")). It calls greenSD::get_tile_green(bbox, zoom, provider = "esri") and uses the raw RGB tile (⁠[[2]]⁠) as the colour source.

Value

• method = "equirectangular", no semantic: 3-band SpatRaster (R, G, B, 0–255). Plot with terra::plotRGB().

• method = "equirectangular", with semantic: 2-layer SpatRaster (depth in metres, land-cover code).

• method = "cylindrical", no semantic: single-layer distance SpatRaster (NA = sky).

• method = "cylindrical", with semantic: 2-layer SpatRaster (depth, semantic class).

References

Lu, X., Li, Z., Cui, Z., Oswald, M. R., Pollefeys, M., & Qin, R. (2020). Geometry-aware satellite-to-ground image synthesis for urban areas. In Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (pp. 859-867).

Examples

dsm <- terra::rast(system.file("test_dsm.tif", package = "viewscape"))
vpt <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# cylindrical distance panorama (no internet needed)
result <- viewscape::pano_view(dsm, vpt, h = 6, method = "cylindrical")

visual_magnitude

Description

Visual Magnitude quantifies the extent of a visible region as perceived by an observer. It is derived from the surface's slope and angle features, alongside the observer's relative distance from the area (Chamberlain & Meitner).

Usage

visual_magnitude(viewshed, dsm)

Arguments

Value

SpatRaster

References

Chamberlain, B. C., & Meitner, M. J. (2013). A route-based visibility analysis for landscape management. Landscape and Urban Planning, 111, 13-24.

See Also

compute_viewshed()

Examples

# Load a viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# load dsm raster
dsm <- terra::rast(system.file("test_dsm.tif", package ="viewscape"))
# Compute viewshed
viewshed <- viewscape::compute_viewshed(dsm = dsm,
                                        viewpoints = test_viewpoint,
                                        offset_viewpoint = 6)
# Compute visual magnitude
vm <- viewscape::visual_magnitude(viewshed, dsm)

visualize_viewshed

Description

The visualize_viewshed function is designed for the visualization of a viewshed analysis, providing users with various options for visualizing the results. The function works with a viewshed object and offers multiple plotting and output types.

Usage

visualize_viewshed(viewshed, plottype = "", outputtype = "")

Arguments

Value

Visualized viewshed as either a raster or polygon object, depending on the outputtype specified.

Examples

# Load a viewpoint
test_viewpoint <- sf::read_sf(system.file("test_viewpoint.shp", package = "viewscape"))
# load dsm raster
dsm <- terra::rast(system.file("test_dsm.tif", package ="viewscape"))
#Compute viewshed
viewshed <- compute_viewshed(dsm = dsm,
                             viewpoints = test_viewpoint,
                             offset_viewpoint = 6)
# Visualize the viewshed as polygons
visualize_viewshed(viewshed, plottype = "polygon")
# Visualize the viewshed as a raster
visualize_viewshed(viewshed, plottype = "raster")
# Get the visualized viewshed as a polygon object
polygon_viewshed <- visualize_viewshed(viewshed,
                                       plottype = "polygon",
                                       outputtype = "polygon")