a Python library to assist in realigning (multi-)polygons (OGC Simple Features) to reference borders
Quick links:
brdr is a Python package that assists in aligning geometric boundaries to reference boundaries. This is an important task in geographic data management to enhance data quality.
- In the context of geographic data management, it is important to have accurate and consistent boundaries for a variety of applications such as calculating areas, analyzing spatial relationships, and visualizing and querying geographic information.
- When creating geographic data, it is often more efficient to derive boundaries from existing reference data rather than collecting new data in the field.
brdrcan be used to align boundaries from new data to reference data, ensuring that the boundaries are accurate and consistent.
The figure below shows:
- the original thematic geometry (blue),
- A reference layer (yellow-black).
- The resulting geometry after alignment with
brdr(green)
brdr provides a variety of side-functionalities to assist in aligning boundaries, including:
- Loading thematic data ((Multi-)Polygons): as a dict, geojson or Web Feature Service (WFS-url)
- Loading reference data ((Multi-)Polygons): as a dict, geojson or Web Feature Service (WFS-url)
- (Flanders-specific) Download reference data from GRB-Flanders
- Align thematic boundaries to reference boundaries with a specific relevant distance (process_dict_thematic)
- Align thematic boundaries to reference boundaries with a series of specified relevant distances (process_series)
- Make use of a 'predictor'-function that aligns thematic boundaries to reference boundaries for 'predicted' interesting relevant distances (predictor)
- Calculating a descriptive formulation of a thematic boundary based on a reference layer
- Geodata-management:
- Implementation of
brdrin business-processes and tooling - Bulk geodata-alignment
- Alignment after reprojection of data
- Cleaning data: In a postprocessing-phase, the algorithm executes sliver-cleanup and validity-cleaning on the resulting geometries
- ...
- Implementation of
- Data-Analysis: Investigate the pattern in deviation and change between thematic and reference boundaries
- Update-detection: Investigate the descriptive formulation before and after alignment to check for (automatic) alignment of geodata
- ...
An implementation of brdr for QGIS can be found at GitHub-brdrQ.
This QGIS- script provides a User Interface to align thematic data to a reference layer, showing the results in the QGIS Table of Contents.
You can install the latest release of brdr from
GitHub or
PyPi:
pip install brdrfrom brdr.aligner import Aligner
from brdr.enums import OpenbaarDomeinStrategy
from brdr.geometry_utils import geom_from_wkt
from brdr.loader import DictLoader
# CREATE AN ALIGNER
aligner = Aligner(
relevant_distance=1,
od_strategy=OpenbaarDomeinStrategy.SNAP_SINGLE_SIDE,
threshold_overlap_percentage=50,
crs="EPSG:31370",
)
# ADD A THEMATIC POLYGON TO THEMATIC DICTIONARY and LOAD into Aligner
thematic_dict = {"theme_id_1": geom_from_wkt("POLYGON ((0 0, 0 9, 5 10, 10 0, 0 0))")}
loader = DictLoader(thematic_dict)
aligner.load_thematic_data(loader)
# ADD A REFERENCE POLYGON TO REFERENCE DICTIONARY and LOAD into Aligner
reference_dict = {"ref_id_1": geom_from_wkt("POLYGON ((0 1, 0 10,8 10,10 1,0 1))")}
loader = DictLoader(reference_dict)
aligner.load_reference_data(loader)
# EXECUTE THE ALIGNMENT
process_result = aligner.process_dict_thematic(relevant_distance=1)
# PRINT RESULTS IN WKT
print("result: " + process_result["theme_id_1"]["result"].wkt)
print("added area: " + process_result["theme_id_1"]["result_diff_plus"].wkt)
print("removed area: " + process_result["theme_id_1"]["result_diff_min"].wkt)
# SHOW RESULTING GEOMETRY AND CHANGES
# from examples import show_map
# show_map(
# {aligner.relevant_distance:(result, result_diff, result_diff_plus, result_diff_min, relevant_intersection, relevant_diff)},
# thematic_dict,
# reference_dict)The resulting figure shows:
- the reference polygon (yellow-black)
- the original geometry (blue)
- the resulting geometry (green line)
- the added zone (green squares)
- the removed zone (red squares)
More examples can be found in Examples
(see also Basic example)
To use brdr, follow these steps:
- Create a Aligner-class with specific parameters:
- relevant_distance (m) (default: 1): Distance-parameter used to decide which parts will be aligned, and which parts remain unchanged.
- od_strategy (enum) (default: SNAP_SINGLE_SIDE): Strategy to align geodata that is not covered by reference-data
- threshold_overlap_percentage (%)(0-100) (default 50)
- crs: The Coordinate Reference System (CRS) (default: EPSG:31370 - Belgian Lambert72)
- Load thematic data
- Load reference data
- Process (align) the thematic data
- Results are returned:
- Resulting geometry
- Differences: parts that are 'different' from the original geometry (positive or negative)
- Positive differences: parts that are added to the original geometry
- Negative differences: parts that are removed form the original geometry
- Relevant intersections: relevant intersecting parts of the reference geometries
- Relevant differences: relevant differences of the reference geometries
The algorithm for alignment is based on 2 main principles:
- Principle of intentionality: Thematic boundaries can consciously or unconsciously deviate from the reference borders. The algorithm should keep notice of that.
- Selective spatial conservation of shape: The resulting geometry should re-use the shape of the reference borders where aligned is of relevance.
The figure below shows a schematic overview of the algorithm:
The algorithm can be split into 3 main phases:
- Initialisation:
- Deciding which reference polygons are candidate-polygons to re-use its shape. The reference candidate polygons are selected based on spatial intersection with the thematic geometry.
- Processing:
- Process all candidate-reference polygons one-by-one
- Calculate relevant zones for each candidate-reference-polygon
- relevant intersections: zones that must be present in the final result
- relevant differences: zones that must be excluded from the final result
- Evaluate each candidate based on their relative zones: which parts must be kept and which parts must be excluded
- Union all kept parts to recompose a resulting geometry
- Post-processing:
- Validation/correction of differences between the original input geometry and the composed intermediate resulting geometry after processing the algorithm
- Technical validation of inner holes and multipolygons that are created by processing the algorithm
- Clean-up slivers
- Make the resulting geometry valid
RESULT:
A new resulting output geometry, aligned to the reference-polygons
PIP_COMPILE_ARGS="-v --strip-extras --no-header --resolver=backtracking --no-emit-options --no-emit-find-links"
pip-compile $PIP_COMPILE_ARGS
pip-compile $PIP_COMPILE_ARGS -o requirements-dev.txt --all-extraspython -m pytest --cov=brdr tests/ --cov-report term-missingA more in-depth description of the algorithm can be found in the following article (in dutch):
- Dieussaert, K., Vanvinckenroye, M., Vermeyen, M., & Van Daele, K. (2024). Grenzen verleggen. Automatische correcties van geografische afbakeningen op verschuivende onderlagen Onderzoeksrapporten Agentschap Onroerend Erfgoed, 332. https://doi.org/10.55465/SXCW6218.
We would love to hear from you and your experiences with
brdr or its sister project brdrQ. The discussions forum is the place to be when:
- You have any questions on using
brdrorbrdrQor their applicability to your use cases - Want to share your experiences with the library
- Have any suggestions for improvements or feature requests
If you have discovered a bug in the brdr library you can report it here:
https://github.com/OnroerendErfgoed/brdr/issues
We try to keep the list of issues as clean as possible. If
you're unsure whether something is a bug, or whether the bug is in brdr
or brdrQ, we encourage you to go through the discussions forum first.
This software was created by Athumi, the Flemish data utility company, and Flanders Heritage Agency.
