Type: Package
Title: Access Global Building Height Datasets
Version: 0.1.3
Description: Provides tools to access, search, and download global 3D building footprint datasets (3D-GloBFP) generated by Che et al. (2024) <doi:10.5194/essd-16-5357-2024>. The package includes functions to retrieve metadata, filter by bounding box, and download building height tiles.
License: MIT + file LICENSE
URL: https://github.com/billbillbilly/gloBFPr
BugReports: https://github.com/billbillbilly/gloBFPr/issues
Encoding: UTF-8
Language: en-US
Depends: R (≥ 4.1)
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
Imports: sf, dplyr, httr2, terra, utils, lwgeom, rlang, cli
RoxygenNote: 7.3.2
VignetteBuilder: knitr, rmarkdown
NeedsCompilation: no
Packaged: 2025-06-17 04:29:36 UTC; yangxiaohao
Author: Xiaohao Yang [aut, cre, cph]
Maintainer: Xiaohao Yang <xiaohaoy111@gmail.com>
Repository: CRAN
Date/Publication: 2025-06-18 07:50:09 UTC

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:

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)