BRDR - Aligning borders

# `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.