R/sector_mask.R

In land-info-lab/viewscape: Viewscape Analysis

#' fov_mask
#' @description The fov_mask function is designed to subset a viewshed based on
#' its viewpoint and the field of view
#'
#' @param viewshed viewshed object, generated by compute_viewshed()
#' @param fov Vector, specifying the field of view with two angles in degree (e.g. c(10,100))
#' for masking a viewshed based on its viewpoints.
#' See details.
#'
#' @details For defining the field of view ('fov'), angles range from 0 to 360 degrees,
#' with 0 inclusive and 360 exclusive. The initial angle must be smaller than the terminal
#' angle in the sequence c(a,b) (a < b). To capture the northeast quadrant of a viewshed,
#' one would use c(0,90), while the eastern quadrant would be delineated by c(45,315) as
#' shown below:
#' \tabular{rrr}{
#' 135 \tab 90 \tab 45 \cr
#' 180 \tab v \tab 0 \cr
#' 225 \tab 270 \tab 315 \cr
#' }
#' Here, 'v' represents the viewpoint, with angles measured counterclockwise from due north.
#'
#'
#' @return viewshed object
#' @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
#' out <- viewscape::fov_mask(viewshed, c(40,160))
#'
#' @seealso [compute_viewshed()]
#' @export
#'

fov_mask <- function(viewshed, fov) {
  viewshed@visible <- sectorMask(viewshed@visible,
                                 viewshed@viewpos,
                                 fov)
  return(viewshed)
}