% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/block.R
\name{generate_block}
\alias{generate_block}
\title{generate_block}
\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{
\item{x}{sf. Building footprint polygons, typically output from \code{\link[=search_3dglobdf]{search_3dglobdf()}}.}

\item{network}{sf or character. Optional road network or path to one. When
supplied, \code{network_source} is ignored.}

\item{network_source}{character. Source for automatic network fetching when
\code{network = NULL}. Either \code{"overture"} (Overture Maps via DuckDB parquet
query, default, requires the \code{duckdb} and \code{DBI} packages) or \code{"osm"}
(OpenStreetMap via the Overpass API, slower for large areas).}

\item{overture_release}{character or \code{NULL}. Overture Maps release string
used when \code{network_source = "overture"}, e.g. \code{"2025-03-19.0"}. The
default \code{NULL} (or \code{"auto"}) queries the public bucket for the newest
release and caches it for the session. See
\url{https://github.com/OvertureMaps/data/releases} for available releases.}

\item{res}{numeric. Raster resolution in metres for the fallback stage. Default \code{2}.}

\item{min_block_area}{numeric. Minimum block area in m^2 below which polygons
are treated as slivers and merged into neighbours (raster stage) or dropped
(polygonize stage). Default \code{500}.}

\item{dc_highway_types}{character vector. Highway class values treated as
dual carriageway candidates (OSM \code{highway} tag or Overture \code{class} column).
Default \code{c("motorway", "trunk")}.}

\item{dc_overlap_threshold}{numeric. Minimum overlap fraction (0-1) for a
line to be considered a duplicate carriageway and removed. Default \code{0.7}.}

\item{quiet}{logical. If \code{TRUE}, suppress cli messages. Default \code{FALSE}.}
}
\value{
A named list with two elements:
\describe{
\item{\code{blocks}}{An \code{sf} polygon object, one row per block, with a
\code{block_id} column. CRS matches the input \code{x}.}
\item{\code{buildings}}{The input \code{x} with an added \code{block_id} integer column
linking each building to its block. Buildings that cannot be assigned
to any block receive \code{NA}.}
}
}
\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).
}
\references{
Yin, H., et al. (2025). UrbanWaterBlocks: A python tool for block-based
urban water management. Sustainable Cities and Society.
}
