Skip to content

Commit 6d38a0e

Browse files
committed
Improved API documentation for geometry checks
1 parent 83c6a2c commit 6d38a0e

File tree

2 files changed

+167
-6
lines changed

2 files changed

+167
-6
lines changed

python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheck.sip.in

Lines changed: 83 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,90 @@
1313
class QgsGeometryCheck
1414
{
1515
%Docstring
16-
This class manages all known geometry check factories.
16+
This class implements a geometry check.
1717

18-
QgsGeometryCheckRegistry is not usually directly created, but rather accessed through
19-
:py:func:`QgsAnalysis.geometryCheckRegistry()`
18+
Geometry checks run over a set of features and can detect errors like topological
19+
or other issues which are reported in the geometry validation panel in QGIS and
20+
help a user to create valid geometries.
21+
22+
Implementing a custom geometry check consists of the following parts
23+
24+
### Writing the check
25+
26+
A new subclass of QgsGeometryCheck needs to be written and at least the following
27+
abstract methods need to be implemented:
28+
29+
- `compatibleGeometryTypes()`
30+
31+
A list of geometry types to which this check applies
32+
33+
- `resolutionMethods()`
34+
35+
A list of names for (automated) resolution methods that can be used to fix errors of this type
36+
37+
- `description()`
38+
39+
A description for the geometry check.
40+
41+
- `id()`
42+
43+
A unique id for this check.
44+
45+
- `checkType()`
46+
47+
One of QgsGeometryCheck.LayerCheck, QgsGeometryCheck.FeatureCheck,QgsGeometryCheck.FeatureNodeCheck
48+
49+
- \link collectErrors() `collectErrors(featurePools, errors, messages, feedback, ids)`\endlink
50+
51+
This method will be called to validate geometries. All geometries which should be validated are passed
52+
into this method with the parameter ids and should be retrieved from the available featurePools to make
53+
use of caching. New errors should be appended to the error list and other message strings to messages.
54+
The method needs to return a tuple (errors, messages).
55+
56+
### Creating a geometry check factory
57+
58+
A Geometry check factory manages meta information for checks. There will always be one single
59+
geometry check factory created per check type, but it's possible that multiple QgsGeometryCheck
60+
instances are created and used in parallel.
61+
62+
A new subclass of QgsGeometryCheckFactory needs to be written and at least the following
63+
abstract methods need to be implemented:
64+
65+
- \link QgsGeometryCheckFactory.createGeometryCheck() `createGeometryCheck(context, configuration)`\endlink
66+
67+
Needs to return a new subclassed QgsGeometryCheck object that has been written in the previous step.
68+
69+
- \link QgsGeometryCheckFactory.id() `id()\endlink
70+
71+
A unique id for this geometry check.
72+
73+
- \link QgsGeometryCheckFactory.description() `description()\endlink
74+
75+
A description for this geometry check that can be presented to the user for more explanation.
76+
77+
- \link QgsGeometryCheckFactory.isCompatible() `QgsGeometryCheckFactory.isCompatible(layer)`\endlink
78+
79+
Returns a boolean that determines if this check is available for a given layer. This often
80+
checks for the geometry type of the layer.
81+
82+
- \link QgsGeometryCheckFactory.flags() `flags()`\endlink
83+
84+
Returns additional flags for a geometry check. If unsure return QgsGeometryCheck.AvailableInValidation.
85+
86+
- \link QgsGeometryCheckFactory.checkType() `checkType()`\endlink
87+
88+
Returns the type of this geometry check.
89+
90+
### Registering the geometry check
91+
92+
Finally the geometry check factory needs to be registered in QGIS, so the system
93+
is aware of the available geometry checks.
94+
95+
.. code-block:: python
96+
97+
# Make sure you always keep a
98+
checkFactory = MyGeometryCheckFactory()
99+
QgsAnalysis.geometryCheckRegistry().registerGeometryCheck(checkFactory)
20100

21101
.. note::
22102

src/analysis/vector/geometry_checker/qgsgeometrycheck.h

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,91 @@ class QgsFeaturePool;
3333

3434
/**
3535
* \ingroup analysis
36-
* This class manages all known geometry check factories.
36+
* This class implements a geometry check.
3737
*
38-
* QgsGeometryCheckRegistry is not usually directly created, but rather accessed through
39-
* QgsAnalysis::geometryCheckRegistry().
38+
* Geometry checks run over a set of features and can detect errors like topological
39+
* or other issues which are reported in the geometry validation panel in QGIS and
40+
* help a user to create valid geometries.
41+
*
42+
* Implementing a custom geometry check consists of the following parts
43+
*
44+
* ### Writing the check
45+
*
46+
* A new subclass of QgsGeometryCheck needs to be written and at least the following
47+
* abstract methods need to be implemented:
48+
*
49+
* - `compatibleGeometryTypes()`
50+
*
51+
* A list of geometry types to which this check applies
52+
*
53+
* - `resolutionMethods()`
54+
*
55+
* A list of names for (automated) resolution methods that can be used to fix errors of this type
56+
*
57+
* - `description()`
58+
*
59+
* A description for the geometry check.
60+
*
61+
* - `id()`
62+
*
63+
* A unique id for this check.
64+
*
65+
* - `checkType()`
66+
*
67+
* One of QgsGeometryCheck.LayerCheck, QgsGeometryCheck.FeatureCheck,QgsGeometryCheck.FeatureNodeCheck
68+
*
69+
* - \link collectErrors() `collectErrors(featurePools, errors, messages, feedback, ids)`\endlink
70+
*
71+
* This method will be called to validate geometries. All geometries which should be validated are passed
72+
* into this method with the parameter ids and should be retrieved from the available featurePools to make
73+
* use of caching. New errors should be appended to the error list and other message strings to messages.
74+
* The method needs to return a tuple (errors, messages).
75+
*
76+
*
77+
* ### Creating a geometry check factory
78+
*
79+
* A Geometry check factory manages meta information for checks. There will always be one single
80+
* geometry check factory created per check type, but it's possible that multiple QgsGeometryCheck
81+
* instances are created and used in parallel.
82+
*
83+
* A new subclass of QgsGeometryCheckFactory needs to be written and at least the following
84+
* abstract methods need to be implemented:
85+
*
86+
* - \link QgsGeometryCheckFactory::createGeometryCheck() `createGeometryCheck(context, configuration)`\endlink
87+
*
88+
* Needs to return a new subclassed QgsGeometryCheck object that has been written in the previous step.
89+
*
90+
* - \link QgsGeometryCheckFactory::id() `id()\endlink
91+
*
92+
* A unique id for this geometry check.
93+
*
94+
* - \link QgsGeometryCheckFactory::description() `description()\endlink
95+
*
96+
* A description for this geometry check that can be presented to the user for more explanation.
97+
*
98+
* - \link QgsGeometryCheckFactory::isCompatible() `QgsGeometryCheckFactory::isCompatible(layer)`\endlink
99+
*
100+
* Returns a boolean that determines if this check is available for a given layer. This often
101+
* checks for the geometry type of the layer.
102+
*
103+
* - \link QgsGeometryCheckFactory::flags() `flags()`\endlink
104+
*
105+
* Returns additional flags for a geometry check. If unsure return QgsGeometryCheck.AvailableInValidation.
106+
*
107+
* - \link QgsGeometryCheckFactory::checkType() `checkType()`\endlink
108+
*
109+
* Returns the type of this geometry check.
110+
*
111+
* ### Registering the geometry check
112+
*
113+
* Finally the geometry check factory needs to be registered in QGIS, so the system
114+
* is aware of the available geometry checks.
115+
*
116+
* \code{.py}
117+
* # Make sure you always keep a
118+
* checkFactory = MyGeometryCheckFactory()
119+
* QgsAnalysis.geometryCheckRegistry().registerGeometryCheck(checkFactory)
120+
* \endcode
40121
*
41122
* \note This class is a technology preview and unstable API.
42123
* \since QGIS 3.4

0 commit comments

Comments
 (0)