Package 'gloBFPr'

get_metadata

Description

Returns a spatial grid (as an sf object) containing metadata and download URLs for global 3D building footprint tiles (3D-GloBFP).

Usage

get_metadata(test = FALSE)

Arguments

test	logic, Ignored during normal use; included for internal testing purposes. Defaults to FALSE.

Details

The metadata of 3D Global Building Footprints (3D-GloBFP) dataset is uploaded on zenodo. More detials about this dataset can to found here.

The data is detailed in the following article

Value

sf a spatial polygon grid with attributes: id, gridID, bounding box coordinates, and download_url.

References

Che, Y., Li, X., Liu, X., Wang, Y., Liao, W., Zheng, X., Zhang, X., Xu, X., Shi, Q., Zhu, J., Zhang, H., Yuan, H., & Dai, Y. (2025). 3D-GloBFP: the first global three-dimensional building footprint dataset. Zenodo. https://doi.org/10.5281/zenodo.15487037

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

Examples

meta <- gloBFPr::get_metadata(test=TRUE)

---

search_3dglobdf

Description

Search and retrieve 3D-GloBFP tiles that intersect a given bounding box or area of interest, with options to return vector or raster outputs including building polygons, binary presence rasters, and height-coded rasters.

Usage

search_3dglobdf(
  bbox,
  metadata,
  crop = FALSE,
  out_type = "poly",
  mask = FALSE,
  cell_size = 1
)

Arguments

bbox	sf, sfc, or a numeric vector (xmin, ymin, xmax, ymax) defining the area of interest.
metadata	sf. Typically output from get_metadata(), containing tile extents and download URLs.
crop	logical. If TRUE, the resulting building footprint geometries will be cropped to the input bbox. Default is FALSE.
out_type	character. Default is 'poly'. Output type(s) to return. Options include: "poly": building footprints as an sf polygon object. "binary_rast": binary terra raster where buildings = 1. "graduated_rast": terra raster encoding building height values. "rast": a named list with both binary and graduated rasters. "all": a named list including the polygon layer and both raster layers.
mask	logical (optional). Default is FALSE. If TRUE, masks the graduated raster using the building footprint layer. Only used when out_type is "graduated_rast", "rast", or "all".
cell_size	numeric (optional). Default is 1. Only used when out_type is "graduated_rast", "rast", or "all".

Value

Varies based on out_type:

• If "poly": an sf object of building footprints.

• If "binary_rast": a binary SpatRaster (terra) indicating building presence.

• If "graduated_rast": a quantitative SpatRaster of building heights.

• If "rast": a named list with two SpatRaster objects: binary and graduated.

• If "all": a named list with poly (sf), binary, and graduated rasters.

Note

The downloading process may take some time, depending on the number and size of building footprint tiles.

This implementation 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.

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

Examples

metadata <- gloBFPr::get_metadata(test=TRUE)
buildings <- gloBFPr::search_3dglobdf(bbox=c(-84.485519,45.636118,-84.462774,45.650639),
                     metadata=metadata)

---