# Building Regulariser
A Python library for regularizing building footprints in geospatial data. This library helps clean up and standardize building polygon geometries by aligning edges to principal directions. Built as an open source alternative to the [ArcGIS Regularize Building Footprint (3D Analyst) tool](https://pro.arcgis.com/en/pro-app/latest/tool-reference/3d-analyst/regularize-building-footprint.htm).
[]()
[]()
## Example Results
Before and after regularization:
<div align="center">
<img src="https://raw.githubusercontent.com/DPIRD-DMA/Building-Regulariser/main/examples/1.png" width="45%" alt="Example 1: Before and After Regularization"/>
<img src="https://raw.githubusercontent.com/DPIRD-DMA/Building-Regulariser/main/examples/2.png" width="45%" alt="Example 2: Before and After Regularization"/>
</div>
## Try in Colab
[![Colab_Button]][Link]
[Link]: https://colab.research.google.com/drive/1xeFxpQCAybgbNjmopiHZb7_Tz1lv8k6A?usp=sharing 'Try Building Regulariser In Colab'
[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab
## Overview
Building footprints extracted from remote sensing imagery often contain noise, irregular edges, and geometric inconsistencies. This library provides tools to regularize these footprints by:
- Aligning edges to principal directions (orthogonal and optional 45-degree angles)
- Converting near-rectangular buildings to perfect rectangles
- Converting near-circular buildings to perfect circles
- Simplifying complex polygons while maintaining their essential shape
- Supporting parallel processing for efficient computation with large datasets
- Fine-tune building alignment with neighboring buildings
Inspired by [RS-building-regularization](https://github.com/niecongchong/RS-building-regularization), this library takes a geometric approach to building regularization with improvements for usability and integration with the GeoPandas ecosystem.
## Installation
```bash
pip install buildingregulariser
```
or
```bash
conda install conda-forge::buildingregulariser
```
or
```bash
uv add buildingregulariser
```
## Quick Start
```python
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")
```
## Features
- **GeoDataFrame Integration**: Works seamlessly with GeoPandas GeoDataFrames
- **Polygon Regularization**: Aligns edges to principal directions
- **45-Degree Support**: Optional alignment to 45-degree angles
- **Align with neighboring buildings**: Align each building with neighboring buildings
- **Circle Detection**: Identifies and converts near-circular shapes to perfect circles
- **Edge Simplification**: Reduces the number of vertices while preserving shape
- **Parallel Processing**: Utilizes multiple CPU cores for faster processing of large datasets
## Usage Examples
### Basic Regularization
```python
from buildingregulariser import regularize_geodataframe
import geopandas as gpd
buildings = gpd.read_file("buildings.gpkg")
regularized = regularize_geodataframe(buildings)
```
### Fine-tuning Regularization Parameters
```python
regularized = regularize_geodataframe(
buildings,
parallel_threshold=2.0, # Higher values allow less edge alignment
simplify_tolerance=0.5, # Controls simplification level, should be 2-3 x the raster pixel size
allow_45_degree=True, # Enable 45-degree angles
allow_circles=True, # Enable circle detection
circle_threshold=0.9 # IOU threshold for circle detection
neighbor_alignment=True, # After regularization try to align each building with neighboring buildings
neighbor_search_distance: float = 100.0, # The search distance around each building to find neighbors
neighbor_max_rotation: float = 10, # The maximum rotation allowed to align with neighbors
)
```
## Parameters
- **geodataframe**: Input GeoDataFrame with polygon geometries
- **parallel_threshold**: Distance threshold for handling parallel lines (default: 1.0)
- **simplify**: If True, applies simplification to the geometry (default: True)
- **simplify_tolerance**: Tolerance for simplification (default: 0.5)
- **allow_45_degree**: If True, allows edges to be oriented at 45-degree angles (default: True)
- **diagonal_threshold_reduction**: Used to reduce the chance of diagonal edges being generated, can be from 0 to 22.5 (default: 15.0)
- **allow_circles**: If True, detects and converts near-circular shapes to perfect circles (default: True)
- **circle_threshold**: Intersection over Union (IoU) threshold for circle detection (default: 0.9)
- **num_cores**: Number of CPU cores to use for parallel processing (default: 1)
- **include_metadata**: Include the main direction, IOU, perimeter and aligned_direction (if used) in output gdf
- **neighbor_alignment**: If True, try to align each building with neighboring buildings (default: False)
- **neighbor_search_distance**: The distance to find neighboring buildings (default: 350.0)
- **neighbor_max_rotation**: The maximum allowable rotation to align with neighbors (default: 10)
## Returns
- A new GeoDataFrame with regularized polygon geometries
## How It Works
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 align each building with neighboring buildings, via rotation around centroid.
## License
This project is licensed under the MIT License
## Acknowledgments
This library was inspired by the [RS-building-regularization](https://github.com/niecongchong/RS-building-regularization) project, with improvements for integration with the GeoPandas ecosystem and enhanced regularization algorithms.
Raw data
{
"_id": null,
"home_page": null,
"name": "buildingregulariser",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "building, segmentation, geospatial, geodataframe, geopandas, regularisation, footprint, geometry, regularization, house",
"author": null,
"author_email": "Nick Wright <nicholas.wright@dpird.wa.gov.au>",
"download_url": "https://files.pythonhosted.org/packages/e5/8d/23aed745edb572e7f14c8c0c391a2f6ef59862ee2bc73b1c5c4a0f40e442/buildingregulariser-0.2.4.tar.gz",
"platform": null,
"description": "# Building Regulariser\n\nA Python library for regularizing building footprints in geospatial data. This library helps clean up and standardize building polygon geometries by aligning edges to principal directions. Built as an open source alternative to the [ArcGIS Regularize Building Footprint (3D Analyst) tool](https://pro.arcgis.com/en/pro-app/latest/tool-reference/3d-analyst/regularize-building-footprint.htm).\n\n[]()\n[]()\n\n## Example Results\n\nBefore and after regularization:\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/DPIRD-DMA/Building-Regulariser/main/examples/1.png\" width=\"45%\" alt=\"Example 1: Before and After Regularization\"/>\n <img src=\"https://raw.githubusercontent.com/DPIRD-DMA/Building-Regulariser/main/examples/2.png\" width=\"45%\" alt=\"Example 2: Before and After Regularization\"/>\n</div>\n\n## Try in Colab\n\n[![Colab_Button]][Link]\n\n[Link]: https://colab.research.google.com/drive/1xeFxpQCAybgbNjmopiHZb7_Tz1lv8k6A?usp=sharing 'Try Building Regulariser In Colab'\n\n[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab\n\n## Overview\n\nBuilding footprints extracted from remote sensing imagery often contain noise, irregular edges, and geometric inconsistencies. This library provides tools to regularize these footprints by:\n\n- Aligning edges to principal directions (orthogonal and optional 45-degree angles)\n- Converting near-rectangular buildings to perfect rectangles\n- Converting near-circular buildings to perfect circles\n- Simplifying complex polygons while maintaining their essential shape\n- Supporting parallel processing for efficient computation with large datasets\n- Fine-tune building alignment with neighboring buildings\n\nInspired by [RS-building-regularization](https://github.com/niecongchong/RS-building-regularization), this library takes a geometric approach to building regularization with improvements for usability and integration with the GeoPandas ecosystem.\n\n## Installation\n\n```bash\npip install buildingregulariser\n```\nor \n```bash\nconda install conda-forge::buildingregulariser\n```\nor \n```bash\nuv add buildingregulariser\n```\n## Quick Start\n\n```python\nimport geopandas as gpd\nfrom buildingregulariser import regularize_geodataframe\n\n# Load your building footprints\nbuildings = gpd.read_file(\"buildings.gpkg\")\n\n# Regularize the building footprints\nregularized_buildings = regularize_geodataframe(\n buildings, \n)\n\n# Save the results\nregularized_buildings.to_file(\"regularized_buildings.gpkg\")\n```\n\n## Features\n\n- **GeoDataFrame Integration**: Works seamlessly with GeoPandas GeoDataFrames\n- **Polygon Regularization**: Aligns edges to principal directions\n- **45-Degree Support**: Optional alignment to 45-degree angles\n- **Align with neighboring buildings**: Align each building with neighboring buildings\n- **Circle Detection**: Identifies and converts near-circular shapes to perfect circles\n- **Edge Simplification**: Reduces the number of vertices while preserving shape\n- **Parallel Processing**: Utilizes multiple CPU cores for faster processing of large datasets\n\n## Usage Examples\n\n### Basic Regularization\n\n```python\nfrom buildingregulariser import regularize_geodataframe\nimport geopandas as gpd\n\nbuildings = gpd.read_file(\"buildings.gpkg\")\nregularized = regularize_geodataframe(buildings)\n```\n\n### Fine-tuning Regularization Parameters\n\n```python\nregularized = regularize_geodataframe(\n buildings,\n parallel_threshold=2.0, # Higher values allow less edge alignment\n simplify_tolerance=0.5, # Controls simplification level, should be 2-3 x the raster pixel size\n allow_45_degree=True, # Enable 45-degree angles\n allow_circles=True, # Enable circle detection\n circle_threshold=0.9 # IOU threshold for circle detection\n neighbor_alignment=True, # After regularization try to align each building with neighboring buildings\n neighbor_search_distance: float = 100.0, # The search distance around each building to find neighbors\n neighbor_max_rotation: float = 10, # The maximum rotation allowed to align with neighbors\n)\n```\n\n## Parameters\n\n- **geodataframe**: Input GeoDataFrame with polygon geometries\n- **parallel_threshold**: Distance threshold for handling parallel lines (default: 1.0)\n- **simplify**: If True, applies simplification to the geometry (default: True)\n- **simplify_tolerance**: Tolerance for simplification (default: 0.5)\n- **allow_45_degree**: If True, allows edges to be oriented at 45-degree angles (default: True)\n- **diagonal_threshold_reduction**: Used to reduce the chance of diagonal edges being generated, can be from 0 to 22.5 (default: 15.0)\n- **allow_circles**: If True, detects and converts near-circular shapes to perfect circles (default: True)\n- **circle_threshold**: Intersection over Union (IoU) threshold for circle detection (default: 0.9)\n- **num_cores**: Number of CPU cores to use for parallel processing (default: 1)\n- **include_metadata**: Include the main direction, IOU, perimeter and aligned_direction (if used) in output gdf\n- **neighbor_alignment**: If True, try to align each building with neighboring buildings (default: False)\n- **neighbor_search_distance**: The distance to find neighboring buildings (default: 350.0)\n- **neighbor_max_rotation**: The maximum allowable rotation to align with neighbors (default: 10)\n\n\n## Returns\n\n- A new GeoDataFrame with regularized polygon geometries\n\n## How It Works\n\n1. **Edge Analysis**: Analyzes each polygon to identify principal directions\n2. **Edge Orientation**: Aligns edges to be parallel, perpendicular, or at 45 degrees to the main direction\n3. **Circle Detection**: Optionally identifies shapes that are nearly circular and converts them to perfect circles\n4. **Edge Connection**: Ensures proper connectivity between oriented edges\n5. **Angle Enforcement**: Post-processing to ensure target angles are precisely maintained\n6. **Neighbor Alignment**: Optionally align each building with neighboring buildings, via rotation around centroid.\n\n## License\n\nThis project is licensed under the MIT License\n\n## Acknowledgments\n\nThis library was inspired by the [RS-building-regularization](https://github.com/niecongchong/RS-building-regularization) project, with improvements for integration with the GeoPandas ecosystem and enhanced regularization algorithms.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for regularizing building footprints in geospatial data. This library helps clean up and standardize building polygon geometries by aligning edges to principal directions.",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/DPIRD-DMA/Building-Regulariser"
},
"split_keywords": [
"building",
" segmentation",
" geospatial",
" geodataframe",
" geopandas",
" regularisation",
" footprint",
" geometry",
" regularization",
" house"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b40875f0755565ec7f4d8beb997558c1250c3e5810c1fd09b762aa92eb7f5028",
"md5": "a8b8db19a6249c85b3111d83d2a87329",
"sha256": "69a02146ac4f5a9c4afbc43e13e3093e4b8afd2c9f1352a8ba77f1053cbbc4e0"
},
"downloads": -1,
"filename": "buildingregulariser-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8b8db19a6249c85b3111d83d2a87329",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 19525,
"upload_time": "2025-07-24T06:21:02",
"upload_time_iso_8601": "2025-07-24T06:21:02.327971Z",
"url": "https://files.pythonhosted.org/packages/b4/08/75f0755565ec7f4d8beb997558c1250c3e5810c1fd09b762aa92eb7f5028/buildingregulariser-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e58d23aed745edb572e7f14c8c0c391a2f6ef59862ee2bc73b1c5c4a0f40e442",
"md5": "2f581dccf1fc062a84ce7ed3e3b19fc2",
"sha256": "29a59fc9d716a91e5ff0c49cda1ab91a7018eea6d1ba6667854468260ba8dd3b"
},
"downloads": -1,
"filename": "buildingregulariser-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "2f581dccf1fc062a84ce7ed3e3b19fc2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20970,
"upload_time": "2025-07-24T06:21:03",
"upload_time_iso_8601": "2025-07-24T06:21:03.579862Z",
"url": "https://files.pythonhosted.org/packages/e5/8d/23aed745edb572e7f14c8c0c391a2f6ef59862ee2bc73b1c5c4a0f40e442/buildingregulariser-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 06:21:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DPIRD-DMA",
"github_project": "Building-Regulariser",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "buildingregulariser"
}
JSON
