% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metrics.R
\name{plot_bgvi_viewshed}
\alias{plot_bgvi_viewshed}
\title{Visualize an Individual Building BGVI Viewshed}
\usage{
plot_bgvi_viewshed(
  x,
  building = 1,
  level = c("bottom", "top"),
  floor = NULL,
  height = NULL,
  orientation = NULL,
  field_of_view = 45,
  datasource_canopy_height = "metachm",
  datasource_greenspace = NULL,
  min_tree_height = 2,
  zoom = 17,
  radius = 800,
  year = NULL,
  resolution = NULL,
  key = NULL,
  plot = TRUE,
  scalebar = TRUE,
  scalebar_unit = c("auto", "km", "m"),
  scalebar_cex = 0.7,
  north_arrow = TRUE,
  quiet = FALSE,
  ...
)
}
\arguments{
\item{x}{sf. Building footprint polygons, typically output from
\code{\link[=search_3dglobdf]{search_3dglobdf()}}. Must include a \code{Height} column.}

\item{building}{Integer row number, or a value from the \code{id} column when \code{id}
is present.}

\item{level}{Character. One of \code{"bottom"} or \code{"top"}. Ignored when \code{floor}
or \code{height} is supplied.}

\item{floor}{Integer floor number to visualize. Floor 1 is 1.7 m above
ground; higher floors add 3 m each.}

\item{height}{Numeric observer offset above ground in metres. Overrides
\code{level} and \code{floor} when supplied.}

\item{orientation}{Optional sector orientation. Supply a bearing in degrees
clockwise from north, or one of \code{"north"}, \code{"northeast"}, \code{"east"},
\code{"southeast"}, \code{"south"}, \code{"southwest"}, \code{"west"}, or \code{"northwest"}.
If \code{NULL}, the full viewshed is used.}

\item{field_of_view}{Numeric angular width in degrees for \code{orientation}.}

\item{datasource_canopy_height, datasource_greenspace, min_tree_height, zoom, radius, year, resolution, key, quiet}{Passed to the BGVI raster preparation workflow; see \code{\link[=get_bgvi]{get_bgvi()}}.}

\item{plot}{Logical. If \code{TRUE}, draw the viewshed map.}

\item{scalebar}{Logical. If \code{TRUE}, add a scale bar using the package's
shared map layout.}

\item{scalebar_unit}{Character. Unit for the scale bar: \code{"auto"}, \code{"km"},
or \code{"m"}.}

\item{scalebar_cex}{Numeric text size for the scale bar and north arrow.}

\item{north_arrow}{Logical. If \code{TRUE}, add a north arrow.}

\item{...}{Additional arguments passed to the initial viewshed \code{plot()}.}
}
\value{
A list containing the selected \code{building}, \code{viewpoint}, observer
\code{height}, \code{gvi}, \code{green_area}, \code{viewshed}, \code{viewshed_raster},
\code{viewshed_area}, \code{radius}, \code{visible_green}, \code{sector_mask}, \code{plot_raster},
\code{dsm}, and \code{binary_green}.
}
\description{
Computes and optionally plots the BGVI viewshed for one building and one
viewpoint height. The function uses the same DSM, green feature layer, target
footprint flattening, and flat-roof handling as \code{\link[=get_bgvi]{get_bgvi()}}, but returns the
diagnostic layers for a single building instead of summary columns for every
building.
}
\examples{
\donttest{
result <- plot_bgvi_viewshed(
  globfp_example,
  building = 1,
  level = "top",
  orientation = "south",
  field_of_view = 60,
  datasource_canopy_height = "metachm",
  key = "YOUR_opentopography_API_KEY"
)
}

}
