Building Regulariser

repository·main·Indexed 42 days ago

https://github.com/dpird-dma/building-regulariser

A Python library for regularizing building footprints in geospatial data. It cleans and standardizes building polygon geometries by aligning edges to principal directions, converting near-rectangles to perfect rectangles and near-circles to perfect circles. The library provides the `regularize_geodataframe` function to process GeoPandas GeoDataFrames, featuring support for parallel processing, neighbor alignment, and geometry cleanup via `cleanup_geometry`.

Tokens: 2.5K
Snippets: 6
Records: 8
Agent score: 53%

What's inside Building Regulariser

How building regularization works
main
The regularization process follows these steps:
1. Edge Analysis: Analyzes each polygon to identify principal directions.
2. Edge Orientation: Aligns edges to be parallel, perpendicular, or at 45 degrees to the main direction.
3. Circle Detection: Optionally identifies shapes that are nearly circular and converts them to perfect circles.
4. Edge Connection: Ensures proper connectivity between oriented edges.
5. Angle Enforcement: Post-processing to ensure target angles are precisely maintained.
6. Neighbor Alignment: Optionally aligns each building with neighboring buildings via rotation around its centroid.
https://github.com/dpird-dma/building-regulariser/blob/main/README.md
Install buildingregulariser
main
You can install the buildingregulariser library using pip, conda, or uv.
```
# Using pip
pip install buildingregulariser

# Using conda
conda install conda-forge::buildingregulariser

# Using uv
uv add buildingregulariser
```
https://github.com/dpird-dma/building-regulariser/blob/main/README.md

Quick Start: Regularize building footprints

main

To regularize building footprints, load your data into a GeoPandas GeoDataFrame and pass it to the regularize_geodataframe function. The function returns a new GeoDataFrame containing the regularized geometries.

import geopandas as gpd
from buildingregulariser import regularize_geodataframe

# Load your building footprints
buildings = gpd.read_file("buildings.gpkg")

# Regularize the building footprints
regularized_buildings = regularize_geodataframe(
    buildings, 
)

# Save the results
regularized_buildings.to_file("regularized_buildings.gpkg")

Use regularize_geodataframe()

main

The primary entry point for the library is regularize_geodataframe. It takes a GeoDataFrame and applies geometric regularization to align edges to principal directions, simplify shapes, and optionally detect circles or align with neighbors.

Parameters:

Parameter	Type	Default	Description
`geodataframe`	GeoDataFrame	Required	Input GeoDataFrame with polygon geometries
`parallel_threshold`	float	`1.0`	Distance threshold for handling parallel lines
`target_crs`	str or `pyproj.CRS`	`None`	Optional CRS to reproject the input to before regularization
`simplify`	bool	`True`	If True, applies simplification to the geometry
`simplify_tolerance`	float	`0.5`	Tolerance for simplification (should be 2-3x the raster pixel size)
`allow_45_degree`	bool	`True`	If True, allows edges to be oriented at 45-degree angles
`diagonal_threshold_reduction`	float	`15.0`	Reduces chance of diagonal edges being generated (0 to 22.5)
`allow_circles`	bool	`True`	If True, detects and converts near-circular shapes to perfect circles
`circle_threshold`	float	`0.9`	Intersection over Union (IoU) threshold for circle detection
`num_cores`	int	`0`	Number of CPU cores to use; 0 uses all available cores
`include_metadata`	bool	`False`	Include main direction, IOU, perimeter, and aligned_direction in output
`neighbor_alignment`	bool	`False`	If True, try to align each building with neighboring buildings
`neighbor_search_distance`	float	`100.0`	The distance to find neighboring buildings
`neighbor_max_rotation`	int	`10`	The maximum allowable rotation to align with neighbors

Returns:

A new GeoDataFrame with regularized polygon geometries.

from buildingregulariser import regularize_geodataframe
import geopandas as gpd

buildings = gpd.read_file("buildings.gpkg")
regularized = regularize_geodataframe(
    buildings,
    parallel_threshold=2.0,
    simplify_tolerance=0.5,
    allow_45_degree=True,
    allow_circles=True,
    circle_threshold=0.9,
    neighbor_alignment=True,
    neighbor_search_distance=100,
    neighbor_max_rotation=10,
)

Clean up geometries with `cleanup_geometry()`
main
The cleanup_geometry function is used to post-process a GeoDataFrame to ensure geometric integrity after regularization. It performs the following steps:
1. Filters out empty or None geometries.
2. Sliver Removal: Uses a sequence of buffer operations (Positive $\rightarrow$ Negative $\rightarrow$ Positive) with a buffer size derived from simplify_tolerance / 50 to remove small slivers.
3. Simplification: Simplifies the geometry using simplify(tolerance=buffer_size, preserve_topology=True) to remove redundant or collinear vertices introduced by the buffering process.
4. Final Cleanup: Removes any geometries that became empty during the process.
```
import geopandas as gpd
from buildingregulariser.coordinator import cleanup_geometry

# result_geodataframe: GeoDataFrame with geometries to clean
# simplify_tolerance: float used for simplification and buffer sizing
cleaned_gdf = cleanup_geometry(result_geodataframe=gdf, simplify_tolerance=0.5)
```
https://github.com/dpird-dma/building-regulariser/blob/main/buildingregulariser/coordinator.py
Regularize GeoDataFrames with regularize_geodataframe
main
The primary entrypoint for the buildingregulariser package is the regularize_geodataframe function. It is used to regularize polygon geometries (such as building footprints) within a GeoDataFrame by aligning their edges to principal directions.
```
from buildingregulariser import regularize_geodataframe

# regularize_geodataframe is the main function for processing GeoDataFrames
# containing polygon geometries.
```
https://github.com/dpird-dma/building-regulariser/blob/main/buildingregulariser/__init__.py
Regularize a GeoDataFrame with `regularize_geodataframe()`
main
The regularize_geodataframe function is the primary entry point for regularizing polygon geometries in a GeoDataFrame. It aligns edges to be parallel, perpendicular, or (optionally) at 45-degree angles to their main direction. It handles reprojection, initial simplification, regularization, geometry cleanup, and can be run in parallel across multiple CPU cores.
Key capabilities:
- Edge Alignment: Aligns edges based on a parallel_threshold.
- Circle Detection: If allow_circles is True, nearly circular polygons are replaced with perfect circles based on an IoU circle_threshold.
- Neighbor Alignment: If neighbor_alignment is True, it aligns polygons with their neighbors within a neighbor_search_distance and neighbor_max_rotation threshold.
- Parallel Processing: Uses num_cores to speed up processing (0 uses all available cores).
- Metadata: Optionally includes regularization metadata (like iou and main_direction) in the output.
```
import geopandas as gpd
from buildingregulariser.coordinator import regularize_geodataframe

# Load your data
gdf = gpd.read_file("buildings.shp")

# Regularize the geometries
regularized_gdf = regularize_geodataframe(
    geodataframe=gdf,
    target_crs="EPSG:3857",
    simplify_tolerance=0.5,
    allow_45_degree=True,
    neighbor_alignment=True,
    neighbor_search_distance=50.0,
    include_metadata=True
)
```
https://github.com/dpird-dma/building-regulariser/blob/main/buildingregulariser/coordinator.py

Configure `regularize_geodataframe` parameters

main

The regularize_geodataframe function accepts several configuration parameters to control the regularization behavior:

Parameter	Type	Default	Description
`geodataframe`	`gpd.GeoDataFrame`	(Required)	Input GeoDataFrame with polygon/multipolygon geometries.
`parallel_threshold`	`float`	`1.0`	Distance threshold for merging nearly parallel adjacent edges.
`target_crs`	`str` or `pyproj.CRS`	`None`	CRS to reproject to before regularization.
`simplify`	`bool`	`True`	Whether to apply initial simplification before regularization.
`simplify_tolerance`	`float`	`0.5`	Tolerance for initial simplification and geometry cleanup.
`allow_45_degree`	`bool`	`True`	Allows edges at 45-degree angles relative to the main direction.
`diagonal_threshold_reduction`	`float`	`15`	Reduction factor (0-22.5) to reduce likelihood of diagonal edges.
`allow_circles`	`bool`	`True`	Whether to replace nearly circular polygons with perfect circles.
`circle_threshold`	`float`	`0.9`	IoU threshold for circle detection (0 to 1).
`num_cores`	`int`	`0`	CPU cores for parallel processing (0 = all available).
`include_metadata`	`bool`	`False`	If True, includes `iou`, `main_direction`, etc., in output.
`neighbor_alignment`	`bool`	`False`	If True, aligns polygons with neighbors after regularization.
`neighbor_search_distance`	`float`	`100.0`	Search radius for neighbor alignment.
`neighbor_max_rotation`	`float`	`10`	Direction threshold (degrees) for neighbor alignment.