Skip to content

Instantly share code, notes, and snippets.

@m-kuhn

m-kuhn/geomchecks.md

Last active August 21, 2018 12:45
Show Gist options
  • Save m-kuhn/ed9ff3a397a0f6e300dc006ee5328c7c to your computer and use it in GitHub Desktop.
Save m-kuhn/ed9ff3a397a0f6e300dc006ee5328c7c to your computer and use it in GitHub Desktop.
Download ZIP
Geometry Checking in QGIS
Raw
geomchecks.md

QGIS Enhancement: Geometry Validation

Date 2018/08/01

Author Matthias Kuhn (@m-kuhn)

Contact matthias@opengis.ch

maintainer @m-kuhn

Version QGIS 3.4

Summary

A basic requirement of many GIS environments is that users are required to always create valid geometries. We therefore propose a system that helps to avoid invalid geometries by

  • transparently fixing common mistakes without user intervention where possible
  • running checks on geometries after adding or editing them
  • guiding the user through fixing errors where they appear

Proposed Solution

If geometry checks have been enabled on a layer, QGIS will

  • autocorrect trivial errors
  • trigger a checker job at feature added / geometry changed / feature deleted time
  • report errors in a geometry valid panel
  • require all jobs to have passed successfully before save

Automatic fixes (single feature)

This class of fixes does not require user intervention and is automatically applied. It is usually very cheap in performance overhead and will be applied to geometries when they enter the edit buffer.

Examples:

  • Remove duplicate vertices
  • Snap to grid if layer has a precision defined

Single Feature Checks

This class of checks can run without any context (apart from some configuration parameters of the check) on a single geometry. They will usually require some user interaction to be resolved.

There is a thread running in the background with a job queue. Whenever a feature is added, a geometry is edited or a feature is deleted:

  • the job queue will be inspected for an already running check on this layer (layer/feature id combination)
  • any pending/ongoing job is cancelled
  • a new job is pushed to the queue

There is a list of unresolved geometry errors for the current edit session.

Whenever a job completes all errors for this feature are removed from the list

If the job reported some errors for this feature, add the errors to the list.

Examples:

  • Self Intersection
  • Multipolygon touch check
  • Multipolygon overlap checks
  • Geometry not empty check

Multi Feature Checks

This class of errors require more than one single feature to be completed. They are often topological checks. Due to their nature of requiring other features for a check, they will usually send a request for additional features to the data provider. This adds I/O overhead which prevents us from running these checks repeatedly immediately after each geometry change.

These checks are therefore performed on a separate queue, which will for now only be run on save, but other suitable times to run this queue might be added (after some time of inacivity, layer change, map tool change, ...).

Examples:

  • Topology Overlap checks
  • Topology Gap checks
  • Topology Missing vertex check

User Interface

Configuration

The vector layer properties are extended with a new geometry validation section. Within this section, individual checks and corrections for a layer can be activated.

Automatic fixes:

  • Fix duplicate vertices

Single feature checks (possibly called "geometry checks"):

  • Is Valid Check
  • Not Empty Check

Multi feature checks (possibly called "topology checks"):

  • Topology Overlap Checks
  • Topology Gap Check
  • Topology Missing Vertex Check

Error reporting

All error reporting will be done on a panel. The panel will show a summary for layers with errors. For each of these layers, a list of errors is shown, next to buttons to show the error feature and error position on the map and optional correction suggestions.

Map Tool warnings on the message bar

We propose to completely remove the reporting of geometry errors on the message bar while a geometry is being edited. These messages are often transient, hard to interpret and track. In case this is objected, it will be made configurable at least (preferably off by default).

Saving

On saving a layer,

  • The single feature check queue will be checked for ongoing jobs or errors. If one of the two conditions is met

    • the project will not (yet) be saved
    • the error panel is set visible and raised to top
    • a warning is shown on the message bar that advices the user to wait or fix errors

  • If there have been changes done since the multi feature check queue has been run last

    • a message is shown to the user, that checks are running
    • after successful completion without errors, the project is saved and a message bar informs about that
    • on errors, the error panel will be raised to the top and the user will need to fix any outstanding errors

Affected Files

qgsvectorlayer.h:

Some methods will have the QgsGeometry or QgsFeature parameter unconsted, to have it updated if an automatic fix has been applied and a new configuration object for these fixes is added.

struct GeometryOptions
    {
      /**
       * Automatically remove duplicate nodes on all geometries which are edited on this layer.
       *
       * \since QGIS 3.4
       */
      bool removeDuplicateNodes = false;

      /**
       * The precision in which geometries on this layer should be saved.
       * Geometries which are edited on this layer will be rounded to multiples of this value (snap to grid).
       * Set to 0.0 to disable.
       *
       * \since QGIS 3.4
       */
      double geometryPrecision = 0.0;
    };
    
    bool updateFeature( /* const */ QgsFeature &feature, bool skipDefaultValues = false );
    bool changeGeometry( QgsFeatureId fid, /* const */ QgsGeometry &geometry, bool skipDefaultValue = false );
    
    // setters and getters for removeDuplicateNodes
    // setters and getters for geometryPrecision
  • The geometry checker code will be refactored to contain a registry of checks and exposed to python.
  • The single geometry checks will be refactored, so they can be run on a single geometry, independent of a FeaturePool
  • The feature pools will be refactored, so they can be run on a vector layer (including uncommitted changes) and not only on data providers.
  • Queues to run the checks as desribed in the first paragraph will be implemented inside the analysis library.

Performance Implications

  • There will be performance implications, but checks and fixes are opt-in. Opt-in vs. opt-out might be reconsidered at a later stage.

Further Considerations/Improvements

But don't we already have tools that do that?

Yes, there are several tools available, but they all are either targeted on different use-cases or have limitations.

Processing algorithms

There is a processing algorithm to make a layer valid.

Caveats:

  • This algorithm produces a new clean layer as output and cannot be used (yet) to fix geometries in place.
  • It only fixes errors that can be fixed automatically

Geometry Checker Plugin

This plugin offers a wide range of functionalities to check and fix geometries iteratively. It can and will be used as a guideline, as well as the many functionalities which are available for it in the analysis library.

Caveats:

  • It does not perform any real-time validation
  • It does only allow to scan the whole layer
  • It does not prevent a user from saving with an unclean dataset
  • It's a plugin and opt-in

Realtime warnings from map tools

Some map tools perform real-time checks of the geometry which is being edited. Errors detected while editing are shown in a message bar as a hint to the user.

Caveats:

  • The message is often partially hidden, hence of limited use
  • The message disappears after a timeout of 5 seconds, unrelated to fixing the error or not
  • The message highlights temporary transitional errors (self-intersections are sometimes required in an intermediary state in the construction of an eventually valid geometry)
  • The message does not help fixing the error

Processing algorithms

There is a processing algorithm to make a layer valid.

Caveats:

  • This algorithm produces a new clean layer as output and cannot be used (yet) to fix geometries in place.
  • It only fixes errors that can be fixed automatically

Geometry Checker Plugin

This plugin offers a wide range of functionalities to check and fix geometries iteratively. It can and will be used as a guideline, as well as the many functionalities which are available for it in the analysis library.

Caveats:

  • It does not perform any real-time validation
  • It does only allow to scan the whole layer
  • It does not prevent a user from saving with an unclean dataset
  • It's a plugin and opt-in

Realtime warnings from map tools

Some map tools perform real-time checks of the geometry which is being edited. Errors detected while editing are shown in a message bar as a hint to the user.

Caveats:

  • The message is often partially hidden, hence of limited use
  • The message disappears after a timeout of 5 seconds, unrelated to fixing the error or not
  • The message highlights temporary transitional errors (self-intersections are sometimes required in an intermediary state in the construction of an eventually valid geometry)
  • The message does not help fixing the error

Backwards Compatibility

(required)

Issue Tracking ID(s)

(optional)

Votes

(required)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment