% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metrics.R
\name{get_metrics}
\alias{get_metrics}
\alias{get_morphology}
\alias{get_neighbors}
\alias{get_bgvi}
\alias{get_dng}
\title{get_metrics}
\usage{
get_morphology(
  x = NULL,
  metrics = c("g_area", "pmeter", "v_surf", "t_surf", "vol", "obb_vol", "pa_ratio",
    "rec", "fra", "cbn", "hem", "cnv", "me_dist", "mp_dist", "vol_exch", "elo_x",
    "elo_y", "elo_z"),
  quiet = FALSE
)

get_neighbors(x = NULL, radius = 500, quiet = FALSE)

get_bgvi(
  x = NULL,
  datasource_canopy_height = "metachm",
  datasource_greenspace = NULL,
  min_tree_height = 2,
  zoom = 17,
  radius = 800,
  year = NULL,
  floor = FALSE,
  floor_step = 3,
  short_building_threshold = 6,
  field_of_view = 45,
  directions = NULL,
  workers = NULL,
  resolution = NULL,
  key = NULL,
  quiet = FALSE
)

get_dng(
  x = NULL,
  datasource = NULL,
  min_tree_height = 2,
  zoom = 17,
  radius = 800,
  min_area = 500,
  unit = c("m2", "ha", "km2"),
  year = NULL,
  network = NULL,
  overpass_url = "https://overpass-api.de/api/interpreter",
  timeout = 180,
  workers = NULL,
  quiet = FALSE
)
}
\arguments{
\item{x}{sf. building footprint polygon, typically output from \code{\link[=search_3dglobdf]{search_3dglobdf()}}}

\item{metrics}{vector. A list of metrics to be computed. All metrics will be computed by default.}

\item{quiet}{logical. If \code{TRUE}, suppress cli messages and progress bars.}

\item{radius}{numeric. (only required for \code{get_neighbors}, \code{get_gbvi}, and
\code{get_dng})
A numeric value specifying the buffer radius (in meters) used to define
the proximity of a building footprint centroid. Default for \code{get_neighbors}, and
\code{get_gbvi} and \code{get_dng} is respectfully 500 and 800.}

\item{datasource_canopy_height}{character or \code{NULL}. Canopy height source for
building the DSM and canopy green feature layer. Currently supports
\code{"metachm"}, \code{"ethCHM"}, or \code{NULL}. If \code{NULL}, the DSM is built
from buildings and DEM only.}

\item{datasource_greenspace}{character or \code{NULL}. Optional 2D greenspace map
tile source for the visible-green feature layer. Supports \code{"esri"} and
\code{"sentinel2"}. If both canopy height and greenspace sources are supplied,
the visible-green layer is the union of height-filtered canopy and 2D
greenspace.}

\item{min_tree_height}{numeric. (only required for \code{get_bgvi} and \code{get_dng})
When \code{datasource_canopy_height} is a canopy height source, minimum height threshold (in
meters) to classify vegetation as trees in the CHM. Default is 2.}

\item{zoom}{numeric. (only required for \code{get_bgvi} and \code{get_dng})
Zoom level of map tile when \code{datasource_greenspace = "esri"} or
\code{datasource_greenspace = "sentinel2"}.
The default is \code{17}. The higher level of zoom will lead to higher resolution
of greenspace data for computing BGVI or DNG.}

\item{year}{numeric. The desired year for Sentinel-2 cloudless mosaic
tiles. (This has to be specified when \code{datasource_greenspace = "sentinel2"})}

\item{floor}{logical. (only required for \code{get_bgvi})
Whether to compute Building Green View Index (BGVI) for each floor level
based on estimated number of floors. Default is \code{FALSE}.}

\item{floor_step}{integer. (only required for \code{get_bgvi} when
\code{floor = TRUE}) Compute GVI every \code{floor_step} floors. The top
estimated floor is always included. Default is \code{1}, meaning every floor.}

\item{short_building_threshold}{numeric. (only required for \code{get_bgvi})
Height threshold in meters for deciding whether a building should use only
the bottom viewpoint in non-floor mode. Default is 6.}

\item{field_of_view}{numeric. (only required for directional \code{get_bgvi})
Angular field of view in degrees for direction-specific GVI. Used only when
\code{directions} is not \code{NULL}. Default is 45.}

\item{directions}{character vector or \code{NULL}. Optional direction names for
direction-specific GVI. Valid values are \code{"southwest"},
\code{"southeast"}, \code{"northeast"}, \code{"northwest"}, \code{"north"},
\code{"east"}, \code{"west"}, and \code{"south"}. If \code{NULL},
\code{field_of_view} is ignored and only non-directional GVI columns are returned.}

\item{workers}{integer. (only required for \code{get_dng}) Number of parallel
workers for per-building distance computation. Defaults to one fewer than
available cores. Use \code{workers = 1} to run sequentially.}

\item{resolution}{numeric or \code{NULL}. (only used by \code{get_bgvi}) Output
raster resolution in meters for the internal DSM used for viewshed
computation. If \code{NULL} (default), the finest native resolution among the
downloaded DEM and canopy height model is used, matching
\code{\link[=get_fused_dsm]{get_fused_dsm()}}. Set explicitly (e.g. \code{1}) to force a finer grid.}

\item{key}{character. (only required for \code{get_bgvi})
API key of OpenTopography.}

\item{datasource}{character. (only required for \code{get_bgvi} and \code{get_dng})
Green/canopy data source. Supported values are \code{"metachm"}, \code{"esri"}, and
\code{"sentinel2"} for \code{get_dng}.}

\item{min_area}{numeric. (only required for \code{get_dng}) The minimum area
(the unit is defined by \code{unit}) of greenspace patches within the proximity of
a building.
For example, when \code{min_area = 500}, any greenspace patches with area less than
500 square meter will be excluded.}

\item{unit}{character. (only required for \code{get_dng}) The unit for
\code{min_area}: 'm2','ha', and 'km2'.}

\item{network}{\code{NULL}, character, or \code{sf}. (only required for \code{get_dng})
Controls whether distances are measured along a real street network instead
of in a straight line. Use \code{NULL} (the default) for straight-line distance,
\code{"osm"} to download a walkable OpenStreetMap network for the study extent,
or supply your own \code{sf} line layer of road/path centre lines. When routing
is requested, the distance is the sum of the walk from the building centroid
to the network, the shortest path along the network, and the walk from the
network to the green-space pixel.}

\item{overpass_url}{character. (only required for \code{get_dng} when
\code{network = "osm"}) Overpass API endpoint used to download the street
network.}

\item{timeout}{numeric. (only required for \code{get_dng} when \code{network = "osm"})
Overpass query timeout in seconds. Default is 180.}
}
\value{
\code{get_morphology} returns an \code{sf} object identical to input \code{x},
with additional columns for:
\itemize{
\item \code{g_area}: Ground area of footprint
\item \code{pmeter}: Perimeter length of footprint
\item \code{v_surf}: Vertical surface area (walls)
\item \code{t_surf}: Total surface area (walls + roof)
\item \code{vol}: Volume (area * height)
\item \code{obb_vol}: Volume of oriented bounding box
\item \code{pa_ratio}: Perimeter-area ratio
\item \code{rec}: Rectangular compactness
\item \code{fra}: Fractal dimension ratio
\item \code{cbn}: Cuboidness index
\item \code{hem}: Hemisphericality index
\item \code{cnv}: Convexity index
\item \code{me_dist}: Mean edge accessibility distance
\item \code{mp_dist}: Mean pairwise distance within the footprint
\item \code{vol_exch}: Volume exchange ratio
\item \code{elo_x/elo_y/elo_z}: Elongation ratios (x/y/z axis)
}

\code{get_neighbors} returns an \code{sf} object identical to input \code{x},
with additional columns for:
\itemize{
\item \code{n_count}: Number of adjacent buildings within the radius.
\item \code{m_ndist}: Mean distance from the building centroid
to neighboring building centroids.
\item \code{min_ndist}: Minimum distance to neighboring building centroids.
\item \code{max_ndist}: Maximum distance to neighboring building centroids.
\item \code{sd_ndist}: Standard deviation of those distances.
}

\code{get_bgvi} returns an \code{sf} object identical to input \code{x},
with additional columns for:
\itemize{
\item \code{mean_gvi}: Mean Building Green View Index value (0 to 1) from selected height(s).
\item \code{bottom_gvi}: Building Green View Index from the bottom
viewpoint, 1.7 m above ground.
\item \code{top_gvi}: Building Green View Index from the top viewpoint.
For short buildings, this is equal to \code{bottom_gvi}.
\item \code{bottom_green_area}: Visible green area (m\eqn{^2}) from the bottom viewpoint.
\item \code{top_green_area}: Visible green area (m\eqn{^2}) from the top viewpoint.
\item \code{mean_green_area}: Mean visible green area (m\eqn{^2}) across viewpoints.
\item \code{min_gvi}, \code{max_gvi}, \code{sd_gvi}: Minimum, maximum,
and standard deviation of Green View Index (GVI) (if \code{floor = TRUE}).
\item \code{estimated_floors}: Estimated number of floors based on building height
(if \code{floor = TRUE}).
}

\code{get_dng} returns an \code{sf} object identical to input \code{x},
with additional columns:
\code{dng}: Distance to nearest green space (tree canopy pixel) in meters,
measured along the street network when \code{network} is supplied; and
\code{dng_method}: either \code{"network"} or \code{"euclidean"}, recording
how each value was obtained. Buildings that cannot reach any green space
through the network fall back to straight-line distance and are flagged
\code{"euclidean"}.
}
\description{
\code{get_morphology}: Computes a set of morphological properties and geometric descriptors for each building footprint polygon.
These include area, perimeter, surface area, volume, shape compactness, elongation, and accessibility measures.
If \code{x} contains a \code{group_id} column, features with the same \code{group_id} are
treated as one building for morphology metrics while the returned rows and
geometries remain unchanged.

\code{get_neighbors}: Computes the number of neighboring buildings and centroid
distance summaries, based on a fixed-radius buffer and
Voronoi-based adjacency.

\code{get_bgvi}: Calculate the Building Green View Index (BGVI) for each building volume.
Neighboring buildings in the internal DSM used for the viewshed are given a
single flat roof elevation (base ground elevation at their centroid, plus
height) rather than following the terrain slope pixel by pixel, matching
\code{\link[=get_fused_dsm]{get_fused_dsm()}}.

\code{get_dng}: Calculate the distance to the nearest greenspace (DNG) patch
for each building volume
}
\details{
When \code{floor = TRUE}, \code{get_bgvi()} estimates the number of floors from
building height and computes GVI from selected floor viewpoints. The
\code{floor_step} argument controls how densely floors are sampled. If
\code{floor_step = 1}, GVI is computed for every estimated floor. If
\code{floor_step > 1}, GVI is computed every \code{floor_step} floors to reduce
runtime; for example, \code{floor_step = 3} samples floors 1, 4, 7, and so on.
The top estimated floor is always included, even when it does not fall on
the step sequence.

If \code{directions} is provided, \code{get_bgvi()} also computes direction-specific
GVI by applying the requested \code{field_of_view} around each direction within
each computed viewshed. The viewshed itself is computed once per viewpoint,
then reused for each direction. Direction-specific columns are named with the
direction suffix, such as \code{gvi_bottom_south}, \code{gvi_top_south},
\code{mean_gvi_south}, \code{min_gvi_south}, \code{max_gvi_south}, and
\code{sd_gvi_south}.
}
\note{
\code{x} must include a unique \code{id} field.
If \code{x} includes \code{group_id}, metrics that represent a whole building are
computed on temporary grouped features and copied back to the original rows.

To request an OpenTopography API token, please visit:
\url{https://portal.opentopography.org/requestService?service=api}

USGS 3DEP 1m/10m raster dataset is currently restricted to academic users.
Academic users can request access to these data via the OpenTopography portal.
Non-academic users can enquire about an enterprise API key by emailing info@opentopography.org.
See OpenTopography Terms of Use for more information on appropriate use of the API.
}
\examples{
library(gloBFPr)
data(globfp_example)
result <- gloBFPr::get_morphology(globfp_example[c(1:3),], quiet = TRUE)

result <- gloBFPr::get_neighbors(globfp_example[c(1:3),], radius = 100)
\donttest{
result <- gloBFPr::get_bgvi(globfp_example[c(1:3),],
                            datasource_canopy_height = "metachm",
                            datasource_greenspace = "esri",
                            key = "YOUR_opentopography_API_KEY")
}

result <- gloBFPr::get_dng(#globfp_example[c(1:3),],
                           datasource = "metachm",
                           unit = "m2")

# Measure along real road and path centre lines instead
result <- gloBFPr::get_dng(#globfp_example[c(1:3),],
                           datasource = "metachm",
                           unit = "m2",
                           network = "osm")
}
\references{
Anna Labetski, Stelios Vitalis, Filip Biljecki, Ken Arroyo Ohori &
Jantien Stoter (2023): 3D building metrics for urban morphology.
International Journal of Geographical Information Science, 37(1):
36-67. DOI: 10.1080/13658816.2022.2103818

Rachid Hamaina, Thomas Leduc, Guillaume Moreau.
Towards Urban Fabrics Characterization Based on Buildings Footprints.
Jerome Gensel; Didier Josselin; Danny Vandenbroucke.
Bridging the Geographic Information Sciences- International AGILE'2012 Conference,
Avignon (France), April, 24-27, 2012, Springer Berlin Heidelberg,
pp.327-346, 2012, 978-3-642-29062-6. 10.1007/978-3-642-290633_18. hal-01347299

Melchiorri, M., Freire, S., Schiavina, M. et al.
The Multi-temporal and Multi-dimensional Global Urban Centre Database to
Delineate and Analyse World Cities. Sci Data 11, 82 (2024).
https://doi.org/10.1038/s41597-023-02691-1

Essential background in Pesaresi, M. et al. (2024) "Advances on the Global Human
Settlement Layer by joint assessment of Earth Observation and population survey data",
International Journal of Digital Earth, 17(1).

Qi, L., Hu, Y., Bu, R., Xiong, Z., Li, B., Zhang, C., ... & Li, C. (2024).
Spatial-temporal patterns and influencing factors of the Building Green View
Index: A new approach for quantifying 3D urban greenery visibility.
Sustainable Cities and Society, 111, 105518.
}
