brdr

a Python library to assist in realigning geometries (OGC Simple Features) to reference borders

PyPI - Version

DOI

Quick links:

• API reference documentation
• Examples

Description

Intro

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.
• brdr can be used to align boundaries from new data to reference data, ensuring that the boundaries are accurate and consistent.

Example

The animated gif below shows the main principle of ‘brdr’: * The visualizatuion on the left: * the original thematic geometry (blue), * A reference layer (yellow-black). * The resulting geometry after alignment with brdr (green)** * The graphic on the right: * X-as: Relevant distance (~distance that change is allowed), that increases * Y-as: Change (%) of the resulting geometry

brdr will ‘detect’ stable situations that result in one or more predictions.

Possible application fields

• Geodata-management:
  • Implementation of brdr in 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
  • …
• Data-Analysis: Investigate the pattern in deviation and change between thematic and reference boundaries
• Update-detection: Investigate the descriptive formula before and after alignment to check for (automatic) alignment of geodata
• …

Installation

You can install the latest release of brdr from GitHub or PyPi:

pip install brdr

API reference

See API Reference

Code examples

See Examples

Scheme

classDiagram
    class Aligner {
        +CRS crs
        +Processor processor
        +load_thematic_data(data)
        +load_reference_data(data)
        +process()
        +predict()
        +evaluate()
    }

    class Processor {
        +process(geometry)
    }

    class AlignerResult {
        +get_results()
    }

    Aligner "1" --* "1" Processor : uses
    Aligner "1" --> "*" AlignerResult : generates

Workflow

To use brdr, These are the minimal steps to execute:

• Create a Aligner-class
  • Load thematic data
  • Load reference data
• Process (or predict or evaluate) the thematic data
• ProcessResults 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

The brdr- processing algorithm

When using brdr to make predictions, every original geometry is processed using the brdr-algorithm:

This algorithm 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

A 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, https://doi.org/10.55465/SXCW6218.

Development

pip-compile

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-extras

tests

python - m
pytest - -cov = brdr
tests / --cov - report
term - missing

Docker

As an example-usage (proof-of-concept), a Dockerfile is created to set up a GRB-specific webservice that ‘predicts’ one or multiple actual geometries for a input-geometry based on the reference source GRB. This webservice is based on ‘brdr’.

This POC can be found at brdr-webservice (GRB-actualisator).

docker build -f Dockerfile . -t grb_webservice
docker run --rm -p 80:80 --name grb_webservice grb_webservice


example can be found at: http://localhost:80/docs#/default/actualiser_actualiser_post

brdr for QGIS: brdrQ-plugin

An implementation of brdr for QGIS can be found at GitHub-brdrQ. This QGIS-plugin provides a User Interface to align thematic data to a reference layer, showing the results in the QGIS Table of Contents.

Motivation & citation

A 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, https://doi.org/10.55465/SXCW6218.

Comments and contributions

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 brdr or brdrQ or 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.

Acknowledgement

This software was created by Athumi, the Flemish data utility company, and Flanders Heritage Agency.