calculate_polygon_metrics: Calculate Geometric Metrics and Filter Fire Polygons (Batch...

In OtsuFire: Fire Scars, Severity and Regeneration Mapping Using 'Otsu' Thresholding

Calculate Geometric Metrics and Filter Fire Polygons (Batch Mode)

Description

Calculates geometric descriptors for fire-affected polygons from a list of input shapefiles. Metrics include area, perimeter, bounding box dimensions, rotated bounding box, and shape ratios. Optionally applies spatial filters and performs attribute joins to enrich outputs.

For each input shapefile, the function: - Computes metrics per polygon and saves a new shapefile. - Applies spatial filters and saves a filtered version. - Optionally joins metrics back to the original input polygons (if 'join_attributes = TRUE').

If 'dissolve = TRUE', adjacent polygons are merged to reconstruct contiguous burned areas. A numeric 'burned_id' is then assigned to each resulting polygon and used in subsequent joins.

## Metrics computed per polygon: - 'area_ha': Area in hectares. - 'bbox_wx': Width of axis-aligned bounding box (x). - 'bbox_hy': Height of axis-aligned bounding box (y). - 'perim_m': Perimeter in meters. - 'p_w_ratio': Perimeter-to-width ratio. - 'h_w_ratio': Height-to-width ratio. - 'burned_id': Polygon ID if 'dissolve = TRUE'.

## Filter behavior: All thresholds are optional. If a threshold is 'NULL', the corresponding filter is skipped. If 'filter_logic = "AND"', all active filters must be satisfied. If '"OR"', any filter match is sufficient.

## Spatial join ('join_attributes = TRUE'): - Attributes from the original input shapefile are preserved via intersection-based joins. - Only input polygons with area ? 'min_input_area_ha' are used. - The join selects, for each input polygon, the intersecting output polygon with the largest shared area. - Only polygons that intersect filtered outputs are retained in the joined outputs. - Optionally, you can restrict which variables from the original shapefile to retain using 'columns_to_keep'.

Arguments

shapefile_paths	Character vector. Paths to input shapefiles.
output_dir	Optional. Directory to save outputs. Defaults to the input file's folder.
area_min_ha	Minimum area in hectares ('area_ha'). Default: 10.
bbox_h_min	Minimum height of axis-aligned bounding box ('bbox_hy'). Default: 630.
mnbbx_wd_min	Minimum width of rotated bounding box. Default: 800.
p_w_ratio_min	Minimum perimeter-to-width ratio. Default: 4.0.
h_w_ratio_min	Minimum height-to-width ratio. Default: 0.35.
output_format	Output format for saved files: '"shp"' or '"geojson"'. Default: '"shp"'.
filter_logic	Logical combination of filters: '"AND"' (default) or '"OR"'.
dissolve	Logical. If 'TRUE', dissolve adjacent polygons before computing metrics. Default: TRUE.
join_attributes	Logical. If 'TRUE', joins filtered/dissolved polygons back to the original shapefile. Default: TRUE.
min_input_area_ha	Minimum area (in hectares) for input polygons used in spatial joins. Default: 10.
overlay_polygons_path	Optional. 'sf' object or path to shapefile to be used for join instead of the input shapefile. Default: 'NULL'.
columns_to_keep	Optional. Character vector of variable names to retain from the original shapefile during spatial join. Default: 'NULL' (keep all).

Value

A named list (one element per input file), each containing:

metrics

Path to shapefile with all polygons and computed metrics.

filtered

Path to shapefile with only polygons passing the filters.

joined_metrics

(If 'join_attributes = TRUE') Path to joined shapefile with original attributes + metrics.

joined_filtered

(If 'join_attributes = TRUE') Path to joined filtered shapefile.

polygons_all

'sf' object of all polygons with computed metrics.

polygons_filtered

'sf' object of polygons that passed the filters.

Note

Examples require large external raster files (hosted on Zenodo). Therefore, they are wrapped#' in dontrun to avoid errors during R CMD check and to ensure portability.

Examples

## Not run: 
burned_files <- list.files("path/to/shapefiles", pattern = "\\.shp$", full.names = TRUE)

results <- calculate_polygon_metrics(
  shapefile_paths = burned_files,
  output_dir = "outputs/",
  area_min_ha = 10,
  bbox_h_min = 600,
  mnbbx_wd_min = 800,
  p_w_ratio_min = 4.0,
  h_w_ratio_min = 0.25,
  output_format = "geojson",
  filter_logic = "AND",
  dissolve = TRUE,
  join_attributes = TRUE,
  min_input_area_ha = 5,
  columns_to_keep = c("CLC_CODE", "ECOR_REGION")
)

## End(Not run)

OtsuFire documentation built on June 13, 2025, 3:01 a.m.