Merge pull request #5512 from nyalldawson/interp

Cleanup and optimise interpolation code

Author: nyalldawson

doc/api_break.dox

@@ -195,6 +195,7 @@ Renamed Classes        {#qgis_api_break_3_0_renamed_classes}
 <tr><td>QgsSymbolV2SelectorDialog<td>QgsSymbolSelectorDialog
 <tr><td>QgsSymbolV2SelectorWidget<td>QgsSymbolSelectorWidget
 <tr><td>QgsTicksScaleBarStyle<td>QgsTicksScaleBarRenderer
+<tr><td>QgsTINInterpolator<td>QgsTinInterpolator
 <tr><td>QgsVectorColorBrewerColorRampV2<td>QgsColorBrewerColorRamp
 <tr><td>QgsVectorColorBrewerColorRampV2Dialog<td>QgsColorBrewerColorRampDialog
 <tr><td>QgsVectorColorBrewerColorRampV2DialogBase<td>QgsColorBrewerColorRampDialogBase
@@ -210,6 +211,7 @@ Renamed Classes        {#qgis_api_break_3_0_renamed_classes}
 <tr><td>QgsVectorRandomColorRampV2<td>QgsLimitedRandomColorRamp
 <tr><td>QgsVectorRandomColorRampV2Dialog<td>QgsLimitedRandomColorRampDialog
 <tr><td>QgsVectorRandomColorRampV2DialogBase<td>QgsLimitedRandomColorRampDialogBase
+<tr><td>vertexData<td>QgsInterpolatorVertexData
 </table>
 
 <table>
@@ -1484,6 +1486,16 @@ QgsIFeatureSelectionManager        {#qgis_api_break_3_0_QgsIFeatureSelectionMana
 - selectedFeaturesIds() has been renamed to selectedFeatureIds()
 
 
+QgsInterpolator        {#qgis_api_break_3_0_QgsInterpolator}
+---------------
+
+- The InputType enum was renamed to SourceType and the enum values were renamed.
+- LayerData.vectorLayer was renamed to LayerData.source
+- LayerData.zCoordInterpolation was renamed to LayerData.valueSource and now takes a QgsInterpolator.ValueSource enum value.
+- LayerData.mInputType was renamed to LayerData.sourceType
+
+
+
 QgsJSONExporter        {#qgis_api_break_3_0_QgsJSONExporter}
 ---------------
 
@@ -2454,7 +2466,7 @@ QgsSymbolsListWidget        {#qgis_api_break_3_0_QgsSymbolsListWidget}
 - expressionContext(), setExpressionContext(), setMapCanvas() and mapCanvas() have been removed in favor of setContext()/context()
 
 
-QgsTINInterpolator        {#qgis_api_break_3_0_QgsTINInterpolator}
+QgsTinInterpolator        {#qgis_api_break_3_0_QgsTinInterpolator}
 ------------------
 
 - The constructor takes a QgsFeedback argument instead of using a QProgressDialog.

python/analysis/interpolation/Line3D.sip

@@ -11,25 +11,46 @@
 
 class QgsIDWInterpolator: QgsInterpolator
 {
+%Docstring
+ Inverse distance weight interpolator.
+%End
 
 %TypeHeaderCode
 #include "qgsidwinterpolator.h"
 %End
   public:
+
     QgsIDWInterpolator( const QList<QgsInterpolator::LayerData> &layerData );
+%Docstring
+ Constructor for QgsIDWInterpolator, with the specified ``layerData`` sources.
+%End
+
+    virtual int interpolatePoint( double x, double y, double &result, QgsFeedback *feedback = 0 );
 
-    virtual int interpolatePoint( double x, double y, double &result );
 
+    void setDistanceCoefficient( double coefficient );
 %Docstring
- Calculates interpolation value for map coordinates x, y
-\param x x-coordinate (in map units)
-\param y y-coordinate (in map units)
-\param result out: interpolation result
-:return: 0 in case of success*
- :rtype: int
+ Sets the distance ``coefficient``, the parameter that sets how the values are
+ weighted with distance. Smaller values mean sharper peaks at the data points.
+
+ Point values are weighted by 1 / ( distance ^ coefficient ).
+
+.. seealso:: distanceCoefficient()
+.. versionadded:: 3.0
 %End
 
-    void setDistanceCoefficient( double p );
+    double distanceCoefficient() const;
+%Docstring
+ Returns the distance coefficient, the parameter that sets how the values are
+ weighted with distance. Smaller values mean sharper peaks at the data points.
+ The default is a coefficient of 2.
+
+ Point values are weighted by 1 / ( distance ^ coefficient ).
+
+.. seealso:: setDistanceCoefficient()
+.. versionadded:: 3.0
+ :rtype: float
+%End
 
 };
 

python/analysis/interpolation/Node.sip

@@ -10,63 +10,117 @@
 
 
 
-struct vertexData
+struct QgsInterpolatorVertexData
 {
+
+  QgsInterpolatorVertexData( double x, double y, double z );
+%Docstring
+ Constructor for QgsInterpolatorVertexData with the specified
+ ``x``, ``y``, and ``z`` coordinate.
+%End
+
+  QgsInterpolatorVertexData();
+%Docstring
+Constructor for QgsInterpolatorVertexData
+%End
+
   double x;
+%Docstring
+X-coordinate
+%End
   double y;
+%Docstring
+Y-coordinate
+%End
   double z;
+%Docstring
+Z-coordinate
+%End
 };
 
 class QgsInterpolator
 {
 %Docstring
  Interface class for interpolations. Interpolators take
-the vertices of a vector layer as base data. The z-Value
-can be an attribute or the z-coordinates in case of 25D types*
+ the vertices of a vector layer as base data. The z-Value
+ can be an attribute or the z-coordinates in case of 3D types.
 %End
 
 %TypeHeaderCode
 #include "qgsinterpolator.h"
 %End
   public:
-    enum InputType
+
+    enum SourceType
     {
-      POINTS,
-      STRUCTURE_LINES,
-      BREAK_LINES
+      SourcePoints,
+      SourceStructureLines,
+      SourceBreakLines,
+    };
+
+    enum ValueSource
+    {
+      ValueAttribute,
+      ValueZ,
+      ValueM,
+    };
+
+    enum Result
+    {
+      Success,
+      Canceled,
+      InvalidSource,
+      FeatureGeometryError,
     };
 
     struct LayerData
     {
-      QgsVectorLayer *vectorLayer;
-      bool zCoordInterpolation;
+      QgsFeatureSource *source;
+%Docstring
+Feature source
+%End
+      QgsInterpolator::ValueSource valueSource;
+%Docstring
+Source for feature values to interpolate
+%End
       int interpolationAttribute;
-      QgsInterpolator::InputType mInputType;
+%Docstring
+Index of feature attribute to use for interpolation
+%End
+      QgsInterpolator::SourceType sourceType;
+%Docstring
+Source type
+%End
     };
 
     QgsInterpolator( const QList<QgsInterpolator::LayerData> &layerData );
 
     virtual ~QgsInterpolator();
 
-    virtual int interpolatePoint( double x, double y, double &result ) = 0;
+    virtual int interpolatePoint( double x, double y, double &result, QgsFeedback *feedback = 0 ) = 0;
 %Docstring
  Calculates interpolation value for map coordinates x, y
-\param x x-coordinate (in map units)
-\param y y-coordinate (in map units)
-\param result out: interpolation result
-:return: 0 in case of success*
+ \param x x-coordinate (in map units)
+ \param y y-coordinate (in map units)
+ \param result out: interpolation result
+ \param feedback optional feedback object for progress and cancelation support
+ :return: 0 in case of success*
  :rtype: int
 %End
 
 
   protected:
 
-    int cacheBaseData();
+    Result cacheBaseData( QgsFeedback *feedback = 0 );
 %Docstring
  Caches the vertex and value data from the provider. All the vertex data
-will be held in virtual memory
-:return: 0 in case of success*
- :rtype: int
+ will be held in virtual memory.
+
+ An optional ``feedback`` argument may be specified to allow cancelation and
+ progress reports from the cache operation.
+
+ :return: Success in case of success
+ :rtype: Result
 %End