Package {gloBFPr}

Add wind / flow vector arrows to a foam map plot

Description

Takes a ggplot object produced by plot_foam_map and overlays velocity arrows sampled on a regular sub-grid.

Usage

add_flow_vectors(
  p,
  r,
  spacing = 20,
  scale = 1,
  colour = "black",
  alpha = 0.6,
  linewidth = 0.25,
  arrow_size = 0.07,
  u_ref = NULL,
  quiet = FALSE
)

Arguments

Value

The same ggplot object with arrows added.

aggregate_block

Description

Aggregate building-level metrics to block level using the output of generate_block(). Additive quantities (areas, volumes, population) are summed by default; per-building indices (shape metrics, elongation ratios, etc.) are averaged. Both defaults can be overridden per column via .fns. Two derived metrics are always added: n_buildings (count of buildings per block) and coverage_ratio (total building footprint area / block area).

Usage

aggregate_block(
  block_output,
  .fns = NULL,
  population = FALSE,
  population_year = 2025,
  residential = FALSE,
  residential_year = 2020,
  quiet = FALSE
)

Arguments

Value

The blocks sf object from block_output with one column per aggregated metric, plus n_buildings and coverage_ratio. When population = TRUE, also includes pop_total. When residential = TRUE, also includes res_prop.

generate_block

Description

Cluster given buildings into blocks based on street network. Uses a two-stage approach: (1) vector polygonization of the road network for well-formed areas, then (2) a raster fallback for buildings that fall in network gaps or dead-end pockets. Blocks with no buildings are dropped.

Before polygonization, dual carriageways (motorways and trunk roads represented as parallel lines) are simplified to single centrelines to prevent artificially narrow slivers between them from being misidentified as blocks. The simplification approach is conceptually adapted from UrbanWaterBlocks (Yin et al., 2025).

Usage

generate_block(
  x,
  network = NULL,
  network_source = c("overture", "osm"),
  overture_release = NULL,
  res = 2,
  min_block_area = 500,
  dc_highway_types = c("motorway", "trunk"),
  dc_overlap_threshold = 0.7,
  quiet = FALSE
)

Arguments

Value

A named list with two elements:

blocks

An sf polygon object, one row per block, with a block_id column. CRS matches the input x.

buildings

The input x with an added block_id integer column linking each building to its block. Buildings that cannot be assigned to any block receive NA.

References

Yin, H., et al. (2025). UrbanWaterBlocks: A python tool for block-based urban water management. Sustainable Cities and Society.

get_3d_world

Description

Export a study area as a 3D scene (inspired by the arnis project): terrain surface, extruded building footprints, and canopy tree objects, written as Wavefront OBJ and/or binary STL files that load directly in Rhino3D and Blender.

The OBJ output contains named objects per layer (terrain, buildings, canopy_trunks, canopy_crowns) and one group per building (⁠building_<id>⁠), so individual buildings remain selectable after import. Ground surface classes (greenspace, roads, sidewalks, paths, water, sand) are part of the terrain object itself, as face groups with their own materials - the terrain is one continuous, detailed surface with differently colored regions, not a stack of separate ribbons. STL has no object concept, so one STL file is written per layer.

Usage

get_3d_world(
  x = NULL,
  bbox = NULL,
  place = NULL,
  terrain = TRUE,
  canopy = "metachm",
  key = NULL,
  dem = NULL,
  canopy_height = NULL,
  height_col = "Height",
  format = c("obj", "stl"),
  out_dir = "world3d",
  min_tree_height = 2,
  tree_window = 5,
  max_trees = 20000,
  simplify_terrain = 1,
  color_by = NULL,
  facade_palette = FALSE,
  roads = NULL,
  overture_release = NULL,
  bridges = TRUE,
  bridge_level_height = 6,
  bridge_ramp = 20,
  bridge_pillar_interval = 25,
  water = NULL,
  sand_buffer = 3,
  surface_res = 2,
  greenspace = NULL,
  greenspace_under_canopy = TRUE,
  greenspace_zoom = 17,
  greenspace_year = NULL,
  all_vox = FALSE,
  vox_size = 1,
  basemap = FALSE,
  local_origin = TRUE,
  crop = FALSE,
  data_source = "GBF",
  quiet = TRUE
)

Arguments

Details

All coordinates are in metres (scene UTM zone). Building walls extend 1 m below their sampled ground elevation when terrain = TRUE to avoid gaps on slopes. Trees are blocky voxel-style objects whose shapes are ported from the arnis project (trunk column, leaf columns, apex cap, and concentric canopy rings). Every tree's total height comes from the canopy height raster; the variant is chosen from that height (compact oaks below 8 m, standard/bushy oaks to 14 m, oak/spruce to 22 m, towering spruce above, with position-hashed variety within each class), then the block size is scaled so the tree matches its measured height exactly.

Ground surface classes are painted into the terrain, not built as separate geometry: a classification grid (surface_res metres in default mode, vox_size in voxel mode) assigns each terrain cell one of ground, greenspace, roads, sidewalks, paths, sand, or water, and the terrain mesh carries these as per-face material groups. Roads follow the arnis method: each segment gets a class-based half-width (motorway/trunk/primary 5 m, secondary 4 m, tertiary 3 m, residential/service 2 m, foot/cycle/path classes 1 m - the arnis highway_block_range defaults), is buffered into a ribbon, and painted as roads (asphalt), sidewalks (concrete; includes Overture subclass = "sidewalk"), or paths (dirt).

Bridges and elevated highways follow arnis's structural approach. Neither OSM nor Overture records deck elevations, so the height is inferred from the segment's level: the deck sits level * bridge_level_height metres (arnis uses 6 blocks per layer) above the highest terrain along the span, ramps linearly down to grade over bridge_ramp metres at each end, and is carried by pillars dropped to the ground every bridge_pillar_interval metres. Decks are solid slabs with railings, sized by the same class-based widths as surface roads. Bridge and tunnel segments are excluded from the terrain surface classification, so a bridge no longer leaves a road painted on the ground beneath it.

Riparian and coastal areas also follow arnis: the terrain under each water body is flattened to one level just below its lowest bank (0.2 m in default mode, one block in voxel mode), painted as water, and fringed with a sand_buffer-metre sand strip along the shoreline.

Vegetation is split across two levels so canopy and lawns are never conflated: tree canopy comes from the canopy height model and is rendered as 3D tree objects, while the greenspace terrain class carries the ground surface. Greenery comes from greenSD's map-tile classification (Esri or Sentinel-2 imagery at greenspace_zoom). Ground under canopy stays grass by default, so a park reads as a continuous lawn with trees standing on it - exactly how arnis places tree objects on grass blocks. Use greenspace_under_canopy = FALSE if you instead want canopy cells cut out of the lawn.

With all_vox = TRUE the whole scene is voxelized the way arnis builds its Minecraft worlds: the DEM becomes a stepped block heightmap, each building footprint is rasterized at vox_size and raised as quantized block columns on a flattened base (extending one block below ground), and the voxel trees stand on the quantized ground. Heights still come from the input data (building Height column, CHM tree heights, DEM terrain) - only the geometry representation changes. Expect larger files than the default mode; increase vox_size to lighten them.

When basemap = TRUE, imagery is retrieved from the Esri World Imagery service; check the Esri terms of use and provide attribution (Esri, Maxar, Earthstar Geographics, and the GIS User Community) when publishing rendered scenes. Footprint holes (courtyards) are not carved in this version; the exterior ring is extruded and a warning is issued when holes are dropped.

Value

(invisibly) a list:

• paths: character vector of written files.

• meshes: named list of in-memory meshes (vertices/faces).

• origin: list with x, y offset and epsg of the scene CRS.

• n_buildings, n_trees: scene composition counts.

• n_trees_detected: trees found in the canopy height model before the max_trees cap - compare with n_trees to see how many were dropped.

• n_bridges: elevated bridge segments built.

Why some trees are missing

Three filters reduce canopy pixels to tree objects. min_tree_height (default 2 m) drops low vegetation; tree_window keeps only one tree per window, so closely spaced trees merge into their tallest neighbour; and max_trees caps the total, keeping the tallest. Compare n_trees_detected with n_trees in the returned object, and lower tree_window or raise max_trees if the model looks sparser than the canopy data. Note that tree_window cannot resolve trees closer together than the CHM resolution: on a coarse (e.g. aggregated) canopy raster, set tree_window at or below the cell size to place one tree per canopy cell.

Examples

example <- gloBFPr::globfp_example
world <- get_3d_world(
  x = example, terrain = FALSE, canopy = NULL,
  out_dir = tempfile("world3d")
)

Fetch ERA5 conditions for OpenFOAM boundary conditions

Description

Downloads one hour of ERA5 reanalysis data (10-m wind components, 2-m temperature, skin temperature) from the Copernicus Climate Data Store for a single location and time step. Returns the values pre-formatted for direct use as arguments to prepare_foam_case() for wind simulation.

ERA5 is a global reanalysis with 0.25 deg (~28 km) spatial resolution and hourly temporal resolution from 1940 to present. It is not a local measurement; treat it as a representative synoptic condition, not a site-specific reading.

Usage

get_era5_met(
  lon,
  lat,
  datetime,
  cds_key = Sys.getenv("CDS_API_KEY"),
  cache_dir = tempdir(),
  quiet = FALSE
)

Arguments

Value

A named list (invisibly) containing:

inlet_velocity

c(u, v, 0) in m/s - direct input for prepare_foam_case(inlet_velocity = ...). x = east, y = north, matching a UTM-projected domain.

z_ref

Reference height for the wind measurement - always 10 m.

T_ref

ERA5 2-m air temperature in K. In wind-only prepare_foam_case() runs, this is used as the uniform reference temperature that switches buoyancy off.

T_skin

ERA5 skin (land-surface) temperature in K. Useful as a T_ground estimate; NULL if unavailable.

wind_speed_ms

Scalar 10-m wind speed in m/s.

wind_dir_deg

Meteorological wind direction in degrees (direction FROM which the wind blows; 0 = from North, 90 = from East).

u10, v10

Raw ERA5 eastward and northward wind components (m/s).

datetime

Rounded POSIXct of the ERA5 time step used.

lon, lat

Site coordinates as supplied.

Authentication

You need a free Copernicus CDS account and a personal access token.

1. Register at https://cds.climate.copernicus.eu

2. Copy your personal access token from your user profile page.

3. Set it once per session: Sys.setenv(CDS_API_KEY = "your-token-here") or store it in ⁠~/.Renviron⁠ so it loads automatically.

The legacy CDS was retired in 2024, so ecmwfr >= 2.0.0 is required for current tokens. This function detects the installed ecmwfr API version and adapts automatically, but on older versions the request will be rejected by the server. Upgrade with install.packages("ecmwfr") if you hit auth errors.

You must also accept the dataset licence once, in the browser, at https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels (the "Terms of use" tab). Requests fail with a licence error until you do.

See Also

prepare_foam_case()

Examples

## Not run: 
Sys.setenv(CDS_API_KEY = "your-token-here")

# Summer evening in Detroit
met <- get_era5_met(
  lon               = -83.05,
  lat               =  42.34,
  datetime          = "2023-07-15 22:00"
)

## ---- Wind simulation ------------------------------------------------
prepare_foam_case(
  case_dir       = "path/to/case",
  stl_file       = "path/to/buildings.stl",
  domain         = list(xmin = 0, xmax = 500, ymin = 0, ymax = 500,
                        zmin = 0, zmax = 200),
  inlet_velocity = met$inlet_velocity,
  z_ref          = met$z_ref,
  T_ref          = met$T_ref
)

## End(Not run)

get_fused_dsm

Description

Generate digital surface model using multiple datasets, including building height map, canopy height map, and terrain model. Each building is given a single flat roof elevation (its own base ground elevation, sampled at its centroid, plus its height) rather than following the terrain slope beneath it pixel by pixel, so buildings on sloped ground do not come out tilted or warped.

Usage

get_fused_dsm(
  x = NULL,
  datasource_canopy_height = "metachm",
  min_tree_height = 2,
  resolution = NULL,
  opentopo_key = NULL,
  key = NULL,
  quiet = TRUE
)

Arguments

Examples

 example <- gloBFPr::globfp_example
 dsm <- get_fused_dsm(x= example, opentopo_key = 'key')

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, quiet = TRUE)

Arguments

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)

get_metrics

Description

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 x contains a group_id column, features with the same group_id are treated as one building for morphology metrics while the returned rows and geometries remain unchanged.

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

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 get_fused_dsm().

get_dng: Calculate the distance to the nearest greenspace (DNG) patch for each building volume

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

Details

When floor = TRUE, get_bgvi() estimates the number of floors from building height and computes GVI from selected floor viewpoints. The floor_step argument controls how densely floors are sampled. If floor_step = 1, GVI is computed for every estimated floor. If floor_step > 1, GVI is computed every floor_step floors to reduce runtime; for example, 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 directions is provided, get_bgvi() also computes direction-specific GVI by applying the requested 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 gvi_bottom_south, gvi_top_south, mean_gvi_south, min_gvi_south, max_gvi_south, and sd_gvi_south.

Value

get_morphology returns an sf object identical to input x, with additional columns for:

• g_area: Ground area of footprint

• pmeter: Perimeter length of footprint

• v_surf: Vertical surface area (walls)

• t_surf: Total surface area (walls + roof)

• vol: Volume (area * height)

• obb_vol: Volume of oriented bounding box

• pa_ratio: Perimeter-area ratio

• rec: Rectangular compactness

• fra: Fractal dimension ratio

• cbn: Cuboidness index

• hem: Hemisphericality index

• cnv: Convexity index

• me_dist: Mean edge accessibility distance

• mp_dist: Mean pairwise distance within the footprint

• vol_exch: Volume exchange ratio

• elo_x/elo_y/elo_z: Elongation ratios (x/y/z axis)

get_neighbors returns an sf object identical to input x, with additional columns for:

• n_count: Number of adjacent buildings within the radius.

• m_ndist: Mean distance from the building centroid to neighboring building centroids.

• min_ndist: Minimum distance to neighboring building centroids.

• max_ndist: Maximum distance to neighboring building centroids.

• sd_ndist: Standard deviation of those distances.

get_bgvi returns an sf object identical to input x, with additional columns for:

• mean_gvi: Mean Building Green View Index value (0 to 1) from selected height(s).

• bottom_gvi: Building Green View Index from the bottom viewpoint, 1.7 m above ground.

• top_gvi: Building Green View Index from the top viewpoint. For short buildings, this is equal to bottom_gvi.

• bottom_green_area: Visible green area (m^2) from the bottom viewpoint.

• top_green_area: Visible green area (m^2) from the top viewpoint.

• mean_green_area: Mean visible green area (m^2) across viewpoints.

• min_gvi, max_gvi, sd_gvi: Minimum, maximum, and standard deviation of Green View Index (GVI) (if floor = TRUE).

• estimated_floors: Estimated number of floors based on building height (if floor = TRUE).

get_dng returns an sf object identical to input x, with additional columns: dng: Distance to nearest green space (tree canopy pixel) in meters, measured along the street network when network is supplied; and dng_method: either "network" or "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 "euclidean".

Note

x must include a unique id field. If x includes 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: 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.

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.

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)

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")

Create a screening-level urban road-noise workflow object

Description

Convenience wrapper around prepare_noisemodelling_inputs(). With run = FALSE, it returns reproducible input layers. With run = TRUE, it runs the official headless NoiseModelling WPS scripts and reads the RECEIVERS_LEVEL output table back into R. The returned noise_map element joins the calculated levels to receiver geometries for point mapping, and isophones contains NoiseModelling's CONTOURING_NOISE_MAP polygons.

Usage

get_noise_map(
  x = NULL,
  height_field = "Height",
  datasource_canopy_height = NULL,
  datasource_greenspace = NULL,
  greenspace_year = NULL,
  greenspace_zoom = 17,
  opentopo_key = NULL,
  roads = NULL,
  greenspace = NULL,
  canopy_height = NULL,
  dem = NULL,
  population = FALSE,
  population_field = NULL,
  population_year = 2025,
  min_tree_height = 2,
  receiver = c("grid", "none"),
  resolution = 10,
  out_dir = NULL,
  write = FALSE,
  run = FALSE,
  nm_path = NULL,
  nm_version = "5.0.1",
  download_nm = TRUE,
  osm_file = NULL,
  osm_remove_tunnels = TRUE,
  osm_eliminate_no_traffic_roads = TRUE,
  java = NULL,
  keep_files = FALSE,
  wall_alpha = 0.1,
  reflection_order = 0,
  max_src_distance = 150,
  max_reflection_distance = 50,
  thread_count = 0,
  diffraction_vertical = FALSE,
  diffraction_horizontal = FALSE,
  export_source_id = FALSE,
  humidity = NULL,
  temperature = NULL,
  favourable_occurrences = NULL,
  rays_name = NULL,
  max_error = NULL,
  frequency_field_prepend = "HZ",
  noise_wps_args = NULL,
  delaunay_max_area = NULL,
  road_width = 2,
  building_buffer = 2,
  iso_levels = c(35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 200),
  iso_field = "LAEQ",
  iso_smooth = 0.5,
  quiet = TRUE
)

Arguments

Value

Prepared noise input layers when run = FALSE; otherwise a list with prepared inputs, receiver-level results, output file paths, and logs.

Building shadow and radiation calculations

Description

svf() computes a Sky View Factor raster from building and optional canopy obstacles.

get_shadow_footprint() computes ground shadow footprints for extruded building polygons.

get_shadow_height() computes shadow height at points or across a terra surface. If shadow_locations is omitted, a terra template is generated around the buildings.

get_radiation() estimates direct, diffuse, and total radiation load on roofs and facades represented by a 3D sf surface grid.

Usage

svf(
  x = NULL,
  height_field = "Height",
  min_tree_height = 2,
  datasource_canopy_height = NULL,
  key = NULL,
  canopy_height = NULL,
  dem = NULL,
  raster_buffer = NULL,
  grid_res = 2,
  extent_buffer = NULL,
  res_angle = 5,
  observer_height = 1.7,
  max_distance = NULL,
  plot = FALSE,
  scalebar = TRUE,
  scalebar_unit = c("auto", "km", "m"),
  scalebar_cex = 0.7,
  north_arrow = TRUE,
  quiet = TRUE
)

get_shadow_footprint(
  x = NULL,
  solar_time = NULL,
  time_zone = NULL,
  azimuth = NULL,
  elevation = NULL,
  height_field = "Height",
  min_tree_height = 2,
  datasource_canopy_height = NULL,
  key = NULL,
  canopy_height = NULL,
  dem = NULL,
  raster_buffer = NULL,
  b = 0.01,
  overlap_shadow = FALSE,
  plot = FALSE,
  plot_overlap_gradient = FALSE,
  scalebar = TRUE,
  scalebar_unit = c("auto", "km", "m"),
  scalebar_cex = 0.7,
  north_arrow = TRUE,
  quiet = TRUE
)

get_shadow_height(
  x = NULL,
  shadow_locations = NULL,
  solar_time = NULL,
  time_zone = NULL,
  azimuth = NULL,
  elevation = NULL,
  height_field = "Height",
  min_tree_height = 2,
  datasource_canopy_height = NULL,
  key = NULL,
  raster_buffer = NULL,
  canopy_height = NULL,
  dem = NULL,
  cell_size = 2,
  extent_buffer = NULL,
  b = 0.01,
  filter_footprint = FALSE,
  quiet = TRUE
)

get_radiation(
  x = NULL,
  grid = NULL,
  solar_time = NULL,
  time_zone = NULL,
  azimuth = NULL,
  elevation = NULL,
  solar_normal,
  solar_diffuse,
  height_field = "Height",
  min_tree_height = 2,
  datasource_canopy_height = NULL,
  key = NULL,
  raster_buffer = NULL,
  canopy_transmissivity = 0.15,
  canopy_height = NULL,
  dem = NULL,
  grid_res = 2,
  ground = FALSE,
  ground_res = NULL,
  offset = 0.01,
  radius = 500,
  svf_res_angle = 15,
  return_list = FALSE,
  plot = FALSE,
  plot_3d = FALSE,
  scalebar = TRUE,
  scalebar_unit = c("auto", "km", "m"),
  scalebar_cex = 0.7,
  north_arrow = TRUE,
  quiet = TRUE
)

Arguments

Details

These functions are implemented directly with sf and terra using a projected 2.5D building model.

Value

get_shadow_footprint() returns an sf polygon layer.

get_shadow_height() returns a terra::SpatRaster for terra locations or a numeric matrix for point locations.

get_radiation() returns an sf point layer with svf, direct, diffuse, and total columns, unless return_list = TRUE.

svf() returns a terra::SpatRaster with Sky View Factor values from 0 to 1.

References

Dorman, M. et al. shadow: Geometric Shadow Calculations. https://github.com/michaeldorman/shadow

GHSL Tile Index

Description

A simple-feature tile index used internally to identify GHSL raster tiles that intersect a requested area of interest.

Usage

ghsl_tiles

Format

An sf object with GHSL tile identifiers and polygon geometry.

Test 3D-GloBFP dataset

Description

A sample dataset containing simplified 3D building footprint information for demonstration and testing purposes.

Usage

globfp_example

Format

A data frame with 369 rows and 3 variables:

id

Numeric. Unique identifier for each building.

Height

Numeric. Estimated height of the building in meters.

geometry

sfc_POLYGON. The building footprint geometry in simple feature (sf) format.

Source

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

data(globfp_example)
head(globfp_example)

Example canopy height raster for the 3D-GloBFP sample

Description

A terra::PackedSpatRaster canopy height map cropped to the bounding box of globfp_example and aggregated from the source resolution for lightweight examples. Convert it with terra::rast() before analysis.

Usage

globfp_example_canopy_height

Format

A terra::PackedSpatRaster with one layer named canopy_height.

Source

metaCHM canopy height data via dsmSearch, downloaded for the globfp_example extent.

Examples

data(globfp_example_canopy_height)
canopy_height <- terra::rast(globfp_example_canopy_height)
canopy_height

Example DEM for the 3D-GloBFP sample

Description

A terra::PackedSpatRaster digital elevation model cropped to the bounding box of globfp_example. Convert it with terra::rast() before analysis.

Usage

globfp_example_dem

Format

A terra::PackedSpatRaster with one layer named dem.

Source

OpenTopography / dsmSearch elevation data, downloaded for the globfp_example extent.

Examples

data(globfp_example_dem)
dem <- terra::rast(globfp_example_dem)
dem

Infer screening-level road traffic inputs from OSM road attributes

Description

Adds traffic volume and speed columns to an OSM road sf object based on the highway class and optional maxspeed, lanes, or oneway values. These values are intended for relative/scenario noise mapping when measured traffic counts are unavailable, not calibrated regulatory noise maps.

Usage

infer_osm_traffic(
  roads,
  defaults = osm_noise_traffic_defaults(),
  use_maxspeed = FALSE,
  use_lanes = FALSE,
  use_oneway = FALSE,
  quiet = TRUE
)

Arguments

Value

An sf object with inferred traffic columns, including speed_kmh, light_veh_h, heavy_veh_h, and NoiseModelling-style ⁠LV_*⁠, ⁠MV_*⁠, ⁠HGV_*⁠, ⁠WAV_*⁠, ⁠WBV_*⁠, and speed columns for day/evening/night.

Install the headless NoiseModelling runner

Description

Downloads and unzips the official headless NoiseModelling release into an R user cache directory. This is used by get_noise_map() when run = TRUE and no nm_path is supplied.

Usage

install_noisemodelling(
  version = "5.0.1",
  destdir = noisemodelling_cache_dir(),
  quiet = TRUE
)

Arguments

Value

Path to the installed NoiseModelling directory.

Default OSM traffic assumptions for screening-level road noise

Description

Returns the built-in lookup table used by infer_osm_traffic() when observed traffic counts are unavailable. The defaults mirror the road-category assumptions embedded in NoiseModelling's Import_OSM.groovy, which cites the Good Practice Guide for Strategic Noise Mapping and the Production of Associated Data on Noise Exposure, version 2. They should still be replaced with local traffic counts whenever available.

Usage

osm_noise_traffic_defaults()

Value

A data frame with OSM highway class, speed, and hourly light/heavy vehicle assumptions.

Visualize an Individual Building BGVI Viewshed

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 get_bgvi(), but returns the diagnostic layers for a single building instead of summary columns for every building.

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

Value

A list containing the selected building, viewpoint, observer height, gvi, green_area, viewshed, viewshed_raster, viewshed_area, radius, visible_green, sector_mask, plot_raster, dsm, and binary_green.

Examples

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"
)

Plot an OpenFOAM pedestrian-level map

Description

Convenience wrapper around ggplot2 for visualising a single layer from the raster returned by sample_foam_slice or read_foam_pedestrian_slice.

Usage

plot_foam_map(
  r,
  layer = "U_mag",
  title = NULL,
  palette = "YlOrRd",
  reverse = FALSE,
  buildings = NULL,
  canopy = NULL,
  legend_title = layer,
  max_u_ref = NULL,
  na_colour = "black",
  scalebar = TRUE,
  scalebar_unit = c("auto", "km", "m"),
  scalebar_cex = 0.7,
  north_arrow = TRUE
)

Arguments

Value

A ggplot object.

Plot a NoiseModelling-style road-noise map

Description

Draws NoiseModelling isosurface polygons underneath roads and buildings when available. If x does not contain official isosurfaces, it falls back to an interpolated receiver surface.

Usage

plot_noise_map(
  x,
  period = "DEN",
  field = "LAEQ",
  resolution = NULL,
  breaks = c(35, 40, 45, 50, 55, 60, 65, 70, 75),
  nodata = -99,
  palette = noise_map_palette(),
  road_col = "white",
  road_alpha = 0.35,
  road_lwd = 1.4,
  building_col = "black",
  legend = TRUE,
  legend_width = 0.26,
  legend_cex = 0.85,
  scalebar = TRUE,
  scalebar_unit = c("auto", "km", "m"),
  scalebar_cex = 0.7,
  north_arrow = TRUE,
  mar = c(0.2, 0.2, 0.2, 0.2),
  add = FALSE,
  ...
)

Arguments

Value

Invisibly returns the isosurface sf object or fallback gloBFPr_noise_surface object used for plotting.

Prepare a transient OpenFOAM case for urban wind

Description

Generates a complete OpenFOAM wind case using buoyantBoussinesqPimpleFoam - a transient, Boussinesq, finite-volume Navier-Stokes solve with a kOmegaSST (URANS) closure - driven by an ABL log-law inlet.

The solver is a buoyant one running an isothermal problem: every surface sits at T_ref and the walls are adiabatic, so the Boussinesq body force is identically zero and the result is pure mechanical flow.

Terrain and canopy are used when supplied and skipped when not. Terrain becomes solid geometry; canopy becomes distributed drag via atmPlantCanopy* rather than solid blocks, because a crown passes and drags air instead of blocking it.

Usage

prepare_foam_case(
  case_dir,
  stl_file,
  domain,
  inlet_velocity = c(5, 0, 0),
  z_ref = 10,
  T_ref = 295,
  sim_hours = NULL,
  n_writes = 8L,
  terrain_stl = NULL,
  terrain_dem = NULL,
  canopy_stl = NULL,
  leaf_area_density = 0.4,
  canopy_heat_source = NULL,
  plant_cd = 0.2,
  z0 = 0.1,
  base_cell_size = 10,
  building_refinement = 2L,
  terrain_refinement = 0L,
  max_cells = 3000000L,
  max_co = NULL,
  n_outer_correctors = 2L,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Invisibly, a list with case_dir, files and params.

Oblique wind

blockMesh emits four separately named lateral patches (xMin, xMax, yMin, yMax) and each is assigned an inlet / outlet / lateral role from the sign of dot(flowDir, outward_normal). Any wind direction works without rotating the domain - unlike the previous generator, which pinned the inlet to the x-min face so that a north wind injected velocity through a face whose normal was -x and effectively nothing entered.

See Also

prepare_openfoam_inputs, prepare_foam_geometry, read_foam_pedestrian_slice

Build terrain, canopy and terrain-based building geometry for a case

Description

Turns the rasters written by prepare_openfoam_inputs into the STL geometry prepare_foam_case needs. Everything is optional: supply what you have and the rest is skipped.

Terrain is recovered from the fused DSM rather than used directly, because the fused DSM is terrain + buildings + canopy and meshing it as ground under a separate building STL would double-count every building. Given how get_fused_dsm() builds it, bare earth comes back exactly as fused_dsm - max(building_height, canopy_height, 0).

Usage

prepare_foam_geometry(
  case_dir,
  fused_dsm = NULL,
  building_height = NULL,
  canopy_height = NULL,
  buildings = NULL,
  height_col = NULL,
  domain = NULL,
  terrain_res = NULL,
  canopy_res = 5,
  min_tree_height = 2,
  base_cell_size = 10,
  skirt = 30,
  quiet = FALSE
)

Arguments

Value

Invisibly, a list with terrain_stl, canopy_stl, building_stl, dem (SpatRaster) and dem_file - feed these straight to prepare_foam_case.

Prepare NoiseModelling-style input layers

Description

Builds a compact set of layers for an integrated or external NoiseModelling workflow: BUILDINGS, ROADS, GROUND, RECEIVERS, and optional DEM. The returned layers can be inspected directly in R and optionally written to a GeoPackage.

Usage

prepare_noisemodelling_inputs(
  x = NULL,
  height_field = "Height",
  datasource_canopy_height = NULL,
  datasource_greenspace = NULL,
  greenspace_year = NULL,
  greenspace_zoom = 17,
  opentopo_key = NULL,
  canopy_height = NULL,
  roads = NULL,
  download_roads = TRUE,
  greenspace = NULL,
  dem = NULL,
  population = FALSE,
  population_field = NULL,
  population_year = 2025,
  min_tree_height = 2,
  receiver = c("grid", "none"),
  resolution = 10,
  ground_default = 0,
  green_ground = 1,
  out_dir = NULL,
  write = FALSE,
  quiet = TRUE
)

Arguments

Value

A list with prepared sf/terra layers and optional GeoPackage path.

Prepare gloBFPr spatial outputs for an OpenFOAM Docker workflow

Description

Collects building, terrain, canopy, and ground-cover data from gloBFPr and writes them into a structured OpenFOAM case folder ready for external CFD simulation (via Docker).

Output layers and their intended role in OpenFOAM:

building STL

Solid geometry for snappyHexMesh

building height raster

Auxiliary mesh-generation reference

binary building raster

Building mask / validation

fused DSM

Optional ground STL source (terrain + buildings + canopy surface)

canopy height raster

Standalone CHM for defining porous-zone extents and drag coefficients in fvOptions / topoSetDict

ground roughness raster (z0)

Per-cell aerodynamic roughness length derived from ESA WorldCover land cover, for nutURoughWallFunction. Building footprint cells and tree-cover cells are set to NA because they are handled by solid geometry and porous zones respectively.

Usage

prepare_openfoam_inputs(
  case_dir,
  bbox = NULL,
  place = NULL,
  buildings_list = NULL,
  data_source = "GBF",
  cell_size = 1,
  crop = FALSE,
  mask = TRUE,
  include_buildings = TRUE,
  include_fused_dsm = TRUE,
  include_tree_canopy = TRUE,
  canopy_source = "metachm",
  min_tree_height = 2,
  include_morphology = TRUE,
  include_neighbors = TRUE,
  include_greenspace = TRUE,
  mask_tree_cover = TRUE,
  landcover_source = c("esa", "esri"),
  landcover_year = 2021,
  include_bgvi = FALSE,
  include_shadow = FALSE,
  include_radiation = FALSE,
  opentopo_key = NULL,
  target_crs = NULL,
  height_col = NULL,
  default_height = 10,
  min_height = 2,
  domain_buffer = 100,
  zmax_buffer = 50,
  stl_name = "buildings.stl",
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

A list with:

case_dir

Absolute path to the OpenFOAM case directory.

data_dir

Absolute path to the gloBFPr data sub-directory.

files

Named list of output file paths (NULL when not produced).

data

Named list of in-memory spatial objects.

domain

Named list with xmin/xmax/ymin/ymax/zmin/zmax for blockMeshDict.

origin

Named numeric vector (x, y, z) of the local coordinate system origin in the input CRS.

crs

CRS of the building data.

height_col

Name of the height column used.

n_buildings

Number of building polygons.

max_building_height

Maximum building height in metres.

max_surface_height

Maximum surface height (buildings + DSM).

include_tree_canopy

Logical flag as supplied.

canopy_source

Canopy data source as supplied.

min_tree_height

Minimum tree height as supplied.

landcover_source

Land-cover dataset used ("esa" or "esri").

landcover_year

Land-cover year used.

Read the pedestrian-level slice and compute wind maps

Description

Reads the pedestrian-level surface sample written by the pedestrianSlice function object and returns a multi-layer SpatRaster. The current OpenFOAM workflow is wind-only, so the velocity layers are the primary result; temperature-derived layers should be approximately zero for neutral wind cases:

T_air

Air temperature (K)

U_mag

Wind speed (m/s)

T_cool

Cooling relative to ambient, T_{ref} - T_{air} (K)

T_cool_flux

\max(T_{cool},0) \times |U| - cool-air transport

Ux, Uy

Horizontal velocity components (m/s)

The case is transient, so time_step selects a physical time in seconds since sunset; "latest" gives the end of the run.

Usage

read_foam_pedestrian_slice(
  case_dir,
  T_ref = NULL,
  time_step = "latest",
  resolution = 2,
  base_cell_size = 10,
  agl_tol = 5,
  trim = "auto",
  canopy = NULL,
  min_canopy_height = 2,
  crs = NA,
  buildings = NULL,
  quiet = FALSE
)

Arguments

Value

A terra::SpatRaster with six layers.

See Also

prepare_foam_case, run_openfoam_docker

Run an OpenFOAM case via Docker

Description

Mounts the case directory into an OpenFOAM Docker container and executes the Allrun script produced by prepare_foam_case(). The generated wind case chains blockMesh -> snappyHexMesh -> buoyantBoussinesqPimpleFoam and writes log files in case_dir.

Docker Desktop must be running and the case_dir path must be under a directory shared with Docker (Docker Desktop -> Settings -> Resources -> File Sharing).

Usage

run_openfoam_docker(
  case_dir,
  image = "opencfd/openfoam-run:2506",
  ncpus = foam_default_ncpus(),
  wait = TRUE,
  quiet = FALSE
)

Arguments

Value

Invisibly returns a list with case_dir, image, and the exit status (0 = success; only meaningful when wait = TRUE).

See Also

prepare_foam_case

Sample OpenFOAM results at pedestrian level and return a raster

Description

Uses OpenFOAM's postProcess -func surfaces utility to cut a horizontal plane at z = 1.5 m (or any height) through the latest time-step, then reads the resulting .raw files into R and returns a multi-layer SpatRaster.

For the current wind workflow, prepare_foam_case() already writes a pedestrian slice during the solver run via the pedestrianSlice function object; use read_foam_pedestrian_slice for that default 1.5 m output. Use this helper to sample other heights or fields after a run.

Usage

sample_foam_slice(
  case_dir,
  fields = c("U", "p"),
  z = 1.5,
  image = "opencfd/openfoam-run:2506",
  resolution = 5,
  time_step = "latestTime",
  interpolate = c("smooth", "focal", "none"),
  idw_power = 2,
  idw_maxdist = NULL,
  buildings = NULL,
  quiet = FALSE
)

Arguments

Value

A terra::SpatRaster with layers named after the sampled fields. Velocity U produces three extra layers: U_mag (speed), Ux, Uy. Building footprints, when available, are attached as attr(x, "buildings").

See Also

plot_foam_map, read_foam_pedestrian_slice

search_3dglobdf

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.

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

Value

Varies based on out_type:

• If "poly": an sf object of building footprints. MULTIPOLYGON geometries are converted to POLYGON geometries while preserving one row per source feature. Polygons that touch or intersect share a group_id, which can be used to treat fragmented rows as one building group.

• 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 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 data_source="GBF"

When using data_source = "GBA", the GlobalBuildingAtlas dataset does not provide unique identifiers for individual building parcels. As a result, the 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.

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.

Examples

## Not run: 
buildings <- gloBFPr::search_3dglobdf(bbox=c(-84.485519,45.636118,-84.462774,45.650639))

## End(Not run)