% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/building_data.R
\name{search_3dglobdf}
\alias{search_3dglobdf}
\title{search_3dglobdf}
\usage{
search_3dglobdf(
  bbox = NULL,
  place = NULL,
  crop = FALSE,
  data_source = "GBF",
  keep_source_id = FALSE,
  out_type = "poly",
  mask = FALSE,
  cell_size = 1,
  quiet = TRUE
)
}
\arguments{
\item{bbox}{\code{sf}, \code{sfc}, or a numeric vector (xmin, ymin, xmax, ymax)
defining the area of interest. This can be ignored if \code{place} is specified.}

\item{place}{vector (optional). A single line address,
e.g. ("1600 Pennsylvania Ave NW, Washington") or a vector of addresses
(c("Madrid", "Barcelona")).}

\item{crop}{logical. If \code{TRUE}, the resulting building footprint geometries
will be cropped to the input \code{bbox}. Default is \code{FALSE}.}

\item{data_source}{character. Building data source to query. Use \code{"GBF"} for
3D-GloBFP (default) or \code{"GBA"}/\code{"gba"} for GlobalBuildingAtlas.}

\item{keep_source_id}{logical. If \code{TRUE}, keep the original source feature
identifier as \code{source_id} when it is available. Default is \code{FALSE}.}

\item{out_type}{character. Default is \code{'poly'}.
Output type(s) to return. Options include:
\itemize{
\item \code{"poly"}: building footprints as an \code{sf} polygon object.
\item \code{"binary_rast"}: binary \code{terra} raster where buildings = 1.
\item \code{"graduated_rast"}: \code{terra} raster encoding building height values.
\item \code{"rast"}: a named list with both binary and graduated rasters.
\item \code{"all"}: a named list including the polygon layer and both raster layers.
}}

\item{mask}{logical (optional). Default is \code{FALSE}. If \code{TRUE}, masks the
graduated raster using the building footprint layer. Only used when \code{out_type}
is \code{"graduated_rast"}, \code{"rast"}, or \code{"all"}.}

\item{cell_size}{numeric (optional). Default is 1. Only used when \code{out_type}
is \code{"graduated_rast"}, \code{"rast"}, or \code{"all"}.}

\item{quiet}{logical. If \code{TRUE}, suppress cli messages and progress output.
Default is \code{TRUE}.}
}
\value{
Varies based on \code{out_type}:
\itemize{
\item If \code{"poly"}: an \code{sf} object of building footprints. \code{MULTIPOLYGON}
geometries are converted to \code{POLYGON} geometries while preserving one row
per source feature. Polygons that touch or intersect share a \code{group_id},
which can be used to treat fragmented rows as one building group.
\item If \code{"binary_rast"}: a binary \code{SpatRaster} (\code{terra}) indicating building presence.
\item If \code{"graduated_rast"}: a quantitative \code{SpatRaster} of building heights.
\item If \code{"rast"}: a named list with two \code{SpatRaster} objects: \code{binary} and \code{graduated}.
\item If \code{"all"}: a named list with \code{poly} (sf), \code{binary}, and \code{graduated} rasters.
}
}
\description{
Search and retrieve 3D building footprint data from 3D-GloBFP or
GlobalBuildingAtlas that intersect a given bounding box or area of interest
(a city), with options to return vector or raster outputs including building
polygons, binary presence rasters, and height-coded rasters.
}
\note{
The downloading process may take some time, depending on the number and size
of building footprint tiles.

This implementation for gloBFP-3D relies on the current structure of the dataset as hosted on Figshare.
It may break if the dataset owner changes the file organization or metadata format.

The server of GlobalBuildingAtlas may have issues sometimes, so users may need to
switch over to gloBFP-3D, which means using \code{data_source="GBF"}

When using \code{data_source = "GBA"}, the GlobalBuildingAtlas dataset does not
provide unique identifiers for individual building parcels. As a result, the
\code{group_id} assigned to overlapping or fragmented polygons may not accurately
reflect true building boundaries in all cases. This limitation may affect
morphological analyses at the individual building level (e.g., footprint area,
perimeter, building-level height statistics). However, the data remains suitable
for environmental simulation purposes such as noise mapping, solar radiation
analysis, and wind flow modelling, where parcel-level identity is less critical.
}
\examples{
\dontrun{
buildings <- gloBFPr::search_3dglobdf(bbox=c(-84.485519,45.636118,-84.462774,45.650639))
}

}
\references{
Che Yangzi, Li Xuecao, Liu Xiaoping, Wang Yuhao, Liao Weilin, Zheng Xianwei,
Zhang Xucai, Xu Xiaocong, Shi Qian, Zhu Jiajun, Zhang Honghui, Yuan Hua, &
Dai Yongjiu (2024). 3D-GloBFP: the first global three-dimensional building
footprint dataset. Earth Syst. Sci. Data, 16, 5357-5374

Zhu X. X., Chen S., Zhang F., Shi Y., & Wang Y. (2025).
GlobalBuildingAtlas: an open global and complete dataset of building
polygons, heights and LoD1 3D models. Earth Syst. Sci. Data, 17, 6647-6668.
}
