Package {geomorphR}

Type: Package
Title: Geometric Features and Footprint Comparison for 'sf' Objects
Version: 0.2.0
Author: Jonathan Cohen [aut, cre]
Maintainer: Jonathan Cohen <cohen.jota@gmail.com>
Description: Extracts reproducible geometric and urban-morphology descriptors from polygon and multipart polygon building footprints stored as 'sf' objects, including area, perimeter, compactness, shape, topology, convexity, orientation, and optional building-height and floor-area metrics. Compares polygon footprints across periods using the intersection-over-union (Jaccard) index (Jaccard, 1912) <doi:10.1111/j.1469-8137.1912.tb05611.x> to identify new constructions, potential demolitions, and footprint changes. Supports vector file formats readable by 'sf', including Shapefiles and GeoPackage (GPKG) vector files with named layers, optional boundary clipping, and reprojection to a common coordinate reference system. Returned 'sf' objects preserve source attributes and geometry for spatial analysis and downstream workflows, with optional parallel processing using 'future' for larger feature-extraction jobs.
License: MIT + file LICENSE
URL: https://github.com/MakiJota/geomorphR
BugReports: https://github.com/MakiJota/geomorphR/issues
Encoding: UTF-8
Imports: sf, dplyr, future, future.apply, progressr
Suggests: testthat (≥ 3.0.0)
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-10-13 10:17:34 UTC; edgardo
Repository: CRAN
Date/Publication: 2026-10-13 10:40:11 UTC

Compare polygon footprints across two spatial files

Description

Reads polygon layers from two vector files and compares their footprints using intersection-over-union (IoU). Inputs may be Shapefiles, GeoPackages, or other formats supported by sf::st_read(). For a GeoPackage containing multiple layers, pass the desired layer names with layer1 and layer2.

Usage

compare_footprints(
  file1,
  file2,
  layer1 = NULL,
  layer2 = NULL,
  boundary_path = NULL,
  boundary_layer = NULL,
  similarity_threshold = 0.7,
  overlap_demolition_threshold = 20,
  year_col = "Year_of_Co",
  year_change_threshold = 2,
  replacement_iou_threshold = 0.5,
  period1 = NULL,
  period2 = NULL,
  is_last_period = FALSE,
  make_valid = TRUE,
  verbose = TRUE
)

Arguments

file1, file2

Character paths to the earlier and later spatial files.

layer1, layer2

Optional layer names to read from file1 and file2. These are useful when either file is a GeoPackage with multiple layers.

boundary_path

Optional path to a polygon boundary file used to clip both input layers before comparison.

boundary_layer

Optional layer name when boundary_path contains multiple layers.

similarity_threshold

Numeric IoU threshold between 0 and 1 for treating footprints as the same building. Defaults to 0.7.

overlap_demolition_threshold

Numeric percentage threshold between 0 and 100 below which an identified demolition is marked as a potential demolition.

year_col

Optional name of a numeric construction-year column present in both layers. Defaults to "Year_of_Co"; year-based replacement detection is skipped if this column is absent from both layers.

year_change_threshold

Numeric construction-year difference that must be exceeded to mark a building as replaced. Defaults to 2 years.

replacement_iou_threshold

Numeric IoU threshold between 0 and 1 used with year_change_threshold to identify replacement demolitions. Defaults to 0.5.

period1, period2

Optional labels for the compared periods. By default, the input file names are used.

is_last_period

Logical; if TRUE, demolition results are not calculated for the first layer.

make_valid

Logical; repair invalid input geometries before comparing.

verbose

Logical; report progress and CRS transformations.

Value

A list of sf objects: new_constructions, clean_constructions, demolitions, gdf1_enriched, and gdf2_enriched. The enriched layers contain the comparison attributes; results are returned in memory and are not written to disk.

Extract geometric and morphological descriptors from polygonal building footprints

Description

Computes footprint descriptors and optional building morphology metrics for an sf object containing POLYGON or MULTIPOLYGON geometries.

Usage

extract_geometric_features(
  buildings_sf,
  verbose = TRUE,
  use_parallel = FALSE,
  n_cores = NULL,
  make_valid = TRUE,
  height_col = NULL,
  floors_col = NULL,
  orientation_col = NULL,
  gfa_col = NULL,
  plot_area_col = NULL
)

Arguments

buildings_sf

An sf object with POLYGON or MULTIPOLYGON geometries.

verbose

Logical; print progress messages when TRUE.

use_parallel

Logical; optional future-based parallel computation.

n_cores

Integer or NULL; number of workers used by future.apply.

make_valid

Logical; call sf::st_make_valid() before extraction.

height_col

Character scalar naming building height in source units.

floors_col

Character scalar naming the number of floors/storeys.

orientation_col

Optional character scalar naming building orientation in degrees.

gfa_col

Optional character scalar naming gross floor area.

plot_area_col

Optional character scalar naming plot/parcel area.

Value

An sf object with appended geometry and morphology features.

Validate source columns used by morphology metrics

Description

Validate source columns used by morphology metrics

Usage

validate_morphology_columns(
  buildings_sf,
  height_col = NULL,
  floors_col = NULL,
  orientation_col = NULL,
  gfa_col = NULL,
  plot_area_col = NULL
)

Arguments

buildings_sf

An sf object or data frame containing source columns.

height_col

Character scalar naming building height.

floors_col

Character scalar naming the number of floors/storeys.

orientation_col

Character scalar naming building orientation in degrees.

gfa_col

Character scalar naming gross floor area.

plot_area_col

Character scalar naming plot/parcel area.

Value

A data frame with one row per requested field and validation status.