Doc, indentation fixes for hillshade renderer

qgis · Jun 1, 2016 · 6428f61 · 6428f61
1 parent 36714d5
commit 6428f61
Show file tree

Hide file tree

Showing 6 changed files with 139 additions and 112 deletions.
diff --git a/python/core/raster/qgshillshaderenderer.sip b/python/core/raster/qgshillshaderenderer.sip
@@ -1,16 +1,34 @@
+/**
+ * @brief A renderer for generating live hillshade models.
+ * @note added in QGIS 2.16
+ */
+
 class QgsHillshadeRenderer : QgsRasterRenderer
 {
 %TypeHeaderCode
     #include "qgshillshaderenderer.h"
 %End
   public:
-    /** Renderer owns color array*/
-    QgsHillshadeRenderer( QgsRasterInterface* input, int band , double lightAzimuth, double lightAngle );
+
+    /**
+     * @brief A renderer for generating live hillshade models.
+     * @param input The input raster interface
+     * @param band The band in the raster to use
+     * @param lightAzimuth The azimuth of the light source
+     * @param lightAltitude The altitude of the light source
+     */
+    QgsHillshadeRenderer( QgsRasterInterface* input, int band, double lightAzimuth, double lightAngle );
 
     ~QgsHillshadeRenderer();
 
     virtual QgsHillshadeRenderer * clone() const /Factory/;
 
+    /**
+     * @brief Factory method to create a new renderer
+     * @param elem A DOM element to create the renderer from.
+     * @param input The raster input interface.
+     * @return A new QgsHillshadeRenderer.
+     */
     static QgsRasterRenderer* create( const QDomElement& elem, QgsRasterInterface* input ) /Factory/;
 
     QgsRasterBlock *block( int bandNo, const QgsRectangle & extent, int width, int height ) /Factory/;
@@ -29,51 +47,51 @@ class QgsHillshadeRenderer : QgsRasterRenderer
     void setBand( int bandNo );
 
     /**
-     * @brief The direction of the light over the raster between 0-360
-     * @return The direction of the light over the raster
+     * Returns the direction of the light over the raster between 0-360.
+     * @see setAzimuth()
      */
     double azimuth() const;
 
-    /**
-     * @brief The angle of the light source over the raster
-     * @return The angle of the light source over the raster
+    /** Returns the angle of the light source over the raster.
+     * @see setAltitude()
      */
     double altitude()  const;
 
-    /**
-     * @brief Z Factor
-     * @return Z Factor
+    /** Returns the Z scaling factor.
+     * @see setZFactor()
      */
     double zFactor()  const;
 
-    /**
-     * @brief Is Multi Directional
-     * @return Is Multi Directional
+    /** Returns true if the renderer is using multi-directional hillshading.
+     * @see setMultiDirectional()
      */
     bool multiDirectional() const;
 
 
     /**
-     * @brief Set the azimith of the light source.
-     * @param azimuth The azimuth of the light source.
+     * @brief Set the azimuth of the light source.
+     * @param azimuth The azimuth of the light source, between 0 and 360.0
+     * @see azimuth()
      */
     void setAzimuth( double azimuth );
 
     /**
      * @brief Set the altitude of the light source
-     * @param altitude The altitude
+     * @param altitude the altitude
+     * @see altitude()
      */
     void setAltitude( double angle );
 
     /**
-     * @brief Set the Z factor of the result image.
-     * @param zfactor The z factor.
+     * @brief Set the Z scaling factor of the result image.
+     * @param zfactor The z factor
+     * @see zFactor()
      */
     void setZFactor( double zfactor );
 
-    /**
-     * @brief Set Is Multi Directional
-     * @param isMultiDirectional Is multi directional
+    /** Sets whether to render using a multi-directional hillshade algorithm.
+     * @param isMultiDirectional set to true to use multi directional rendering
+     * @see multiDirectional()
      */
     void setMultiDirectional( bool isMultiDirectional );
 };
diff --git a/python/gui/raster/qgshillshaderendererwidget.sip b/python/gui/raster/qgshillshaderendererwidget.sip
@@ -1,5 +1,7 @@
 /**
  * @brief Renderer widget for the hill shade renderer.
+ * @ingroup gui
+ * @note added in QGIS 2.16
  */
 class QgsHillshadeRendererWidget: QgsRasterRendererWidget
 {
@@ -34,51 +36,53 @@ class QgsHillshadeRendererWidget: QgsRasterRendererWidget
     void setFromRenderer( const QgsRasterRenderer* r );
 
     /**
-     * @brief The direction of the light over the raster between 0-360
-     * @return The direction of the light over the raster
+     * Returns the direction of the light over the raster between 0-360.
+     * @see setAzimuth()
      */
     double azimuth() const;
 
-    /**
-     * @brief The angle of the light source over the raster
-     * @return The angle of the light source over the raster
+    /** Returns the angle of the light source over the raster.
+     * @see setAltitude()
      */
     double altitude()  const;
 
-    /**
-     * @brief Z Factor
-     * @return Z Factor
+    /** Returns the Z scaling factor.
+     * @see setZFactor()
      */
     double zFactor()  const;
 
     /**
-     * @brief multiDirectional
-     * @return multiDirectional
+     * Returns true if the renderer should use the multi-directional hillshade algorithm.
+     * @see setMultiDirectional()
      */
     bool multiDirectional() const;
 
   public slots:
+
     /**
      * @brief Set the altitude of the light source
-     * @param altitude The altitude
+     * @param altitude the altitude
+     * @see altitude()
      */
     void setAltitude( double altitude );
 
     /**
-     * @brief Set the azimith of the light source.
-     * @param azimuth The azimuth of the light source.
+     * @brief Set the azimuth of the light source.
+     * @param azimuth The azimuth of the light source, between 0 and 360.0
+     * @see azimuth()
      */
     void setAzimuth( double azimuth );
 
     /**
-     * @brief Set the Z factor of the result image.
-     * @param zfactor The z factor.
+     * @brief Set the Z scaling factor of the result image.
+     * @param zfactor The z factor
+     * @see zFactor()
      */
     void setZFactor( double zfactor );
 
-    /**
-     * @brief set MultiDirectional
-     * @param isMultiDirectional
+    /** Sets whether to render using a multi-directional hillshade algorithm.
+     * @param isMultiDirectional set to true to use multi directional rendering
+     * @see multiDirectional()
      */
     void setMultiDirectional( bool isMultiDirectional);
 };
diff --git a/src/core/raster/qgshillshaderenderer.cpp b/src/core/raster/qgshillshaderenderer.cpp
@@ -54,10 +54,10 @@ QgsRasterRenderer *QgsHillshadeRenderer::create( const QDomElement &elem, QgsRas
   double azimuth = elem.attribute( "azimuth", "315" ).toDouble();
   double angle = elem.attribute( "angle", "45" ).toDouble();
   double zFactor = elem.attribute( "zfactor", "1" ).toDouble();
-  int multiDirection = elem.attribute( "multidirection", "0" ).toInt();
+  bool multiDirectional = elem.attribute( "multidirection", "0" ).toInt();
   QgsHillshadeRenderer* r = new QgsHillshadeRenderer( input, band, azimuth , angle );
   r->setZFactor( zFactor );
-  r->setMultiDirectional( multiDirection > 0 );
+  r->setMultiDirectional( multiDirectional );
   return r;
 }
 
@@ -112,10 +112,10 @@ QgsRasterBlock *QgsHillshadeRenderer::block( int bandNo, const QgsRectangle &ext
   double sinZenithRad = sin( zenithRad );
 
   // Multi direction hillshade: http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf
-  double angle0Rad = (-1 * mLightAzimuth - 45 - 45 * 0.5) * M_PI / 180.0;
-  double angle1Rad = (-1 * mLightAzimuth - 45 * 0.5) * M_PI / 180.0;
-  double angle2Rad = (-1 * mLightAzimuth + 45 * 0.5) * M_PI / 180.0;
-  double angle3Rad = (-1 * mLightAzimuth + 45 + 45 * 0.5) * M_PI / 180.0;
+  double angle0Rad = ( -1 * mLightAzimuth - 45 - 45 * 0.5 ) * M_PI / 180.0;
+  double angle1Rad = ( -1 * mLightAzimuth - 45 * 0.5 ) * M_PI / 180.0;
+  double angle2Rad = ( -1 * mLightAzimuth + 45 * 0.5 ) * M_PI / 180.0;
+  double angle3Rad = ( -1 * mLightAzimuth + 45 + 45 * 0.5 ) * M_PI / 180.0;
 
   QRgb myDefaultColor = NODATA_COLOR;
 
@@ -197,32 +197,32 @@ QgsRasterBlock *QgsHillshadeRenderer::block( int bandNo, const QgsRectangle &ext
 
 
       double grayValue;
-      if( !mMultiDirectional )
+      if ( !mMultiDirectional )
       {
-          // Standard single direction hillshade
-          grayValue = qBound( 0.0, 255.0 * ( cosZenithRad * cos( slopeRad )
-                                             + sinZenithRad * sin( slopeRad )
-                                             * cos( azimuthRad - aspectRad )) , 255.0 );
+        // Standard single direction hillshade
+        grayValue = qBound( 0.0, 255.0 * ( cosZenithRad * cos( slopeRad )
+                                           + sinZenithRad * sin( slopeRad )
+                                           * cos( azimuthRad - aspectRad ) ) , 255.0 );
       }
       else
       {
-          // Weighted multi direction as in http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf
-          double weight0 = sin( aspectRad - angle0Rad );
-          double weight1 = sin( aspectRad - angle1Rad );
-          double weight2 = sin( aspectRad - angle2Rad );
-          double weight3 = sin( aspectRad - angle3Rad );
-          weight0 = weight0 * weight0;
-          weight1 = weight1 * weight1;
-          weight2 = weight2 * weight2;
-          weight3 = weight3 * weight3;
-
-          double cosSlope = cosZenithRad * cos( slopeRad );
-          double sinSlope = sinZenithRad * sin( slopeRad );
-          double color0 = cosSlope + sinSlope * cos( angle0Rad - aspectRad ) ;
-          double color1 = cosSlope + sinSlope * cos( angle1Rad - aspectRad ) ;
-          double color2 = cosSlope + sinSlope * cos( angle2Rad - aspectRad ) ;
-          double color3 = cosSlope + sinSlope * cos( angle3Rad - aspectRad ) ;
-          grayValue = qBound(0.0, 255 * ( weight0 * color0 + weight1 * color1 + weight2 * color2 + weight3 * color3 ) * 0.5, 255.0);
+        // Weighted multi direction as in http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf
+        double weight0 = sin( aspectRad - angle0Rad );
+        double weight1 = sin( aspectRad - angle1Rad );
+        double weight2 = sin( aspectRad - angle2Rad );
+        double weight3 = sin( aspectRad - angle3Rad );
+        weight0 = weight0 * weight0;
+        weight1 = weight1 * weight1;
+        weight2 = weight2 * weight2;
+        weight3 = weight3 * weight3;
+
+        double cosSlope = cosZenithRad * cos( slopeRad );
+        double sinSlope = sinZenithRad * sin( slopeRad );
+        double color0 = cosSlope + sinSlope * cos( angle0Rad - aspectRad ) ;
+        double color1 = cosSlope + sinSlope * cos( angle1Rad - aspectRad ) ;
+        double color2 = cosSlope + sinSlope * cos( angle2Rad - aspectRad ) ;
+        double color3 = cosSlope + sinSlope * cos( angle3Rad - aspectRad ) ;
+        grayValue = qBound( 0.0, 255 * ( weight0 * color0 + weight1 * color1 + weight2 * color2 + weight3 * color3 ) * 0.5, 255.0 );
       }
       outputBlock->setColor( i, j, qRgb( grayValue, grayValue, grayValue ) );
     }

diff --git a/src/core/raster/qgshillshaderenderer.h b/src/core/raster/qgshillshaderenderer.h
@@ -28,6 +28,7 @@ class QgsRasterInterface;
 
 /**
  * @brief A renderer for generating live hillshade models.
+ * @note added in QGIS 2.16
  */
 class CORE_EXPORT QgsHillshadeRenderer : public QgsRasterRenderer
 {
@@ -39,7 +40,7 @@ class CORE_EXPORT QgsHillshadeRenderer : public QgsRasterRenderer
      * @param lightAzimuth The azimuth of the light source
      * @param lightAltitude The altitude of the light source
      */
-    QgsHillshadeRenderer( QgsRasterInterface* input, int band , double lightAzimuth, double lightAltitude );
+    QgsHillshadeRenderer( QgsRasterInterface* input, int band, double lightAzimuth, double lightAltitude );
 
     QgsHillshadeRenderer * clone() const override;
 
@@ -67,59 +68,59 @@ class CORE_EXPORT QgsHillshadeRenderer : public QgsRasterRenderer
     void setBand( int bandNo );
 
     /**
-     * @brief The direction of the light over the raster between 0-360
-     * @return The direction of the light over the raster
+     * Returns the direction of the light over the raster between 0-360.
+     * @see setAzimuth()
      */
     double azimuth() const { return mLightAzimuth; }
 
-    /**
-     * @brief The angle of the light source over the raster
-     * @return The angle of the light source over the raster
+    /** Returns the angle of the light source over the raster.
+     * @see setAltitude()
      */
     double altitude()  const { return mLightAngle; }
 
-    /**
-     * @brief Z Factor
-     * @return Z Factor
+    /** Returns the Z scaling factor.
+     * @see setZFactor()
      */
     double zFactor()  const { return mZFactor; }
 
-    /**
-     * @brief Is Multi Directional
-     * @return Is Multi Directional
+    /** Returns true if the renderer is using multi-directional hillshading.
+     * @see setMultiDirectional()
      */
     bool multiDirectional() const { return mMultiDirectional; }
 
     /**
-     * @brief Set the azimith of the light source.
-     * @param azimuth The azimuth of the light source.
+     * @brief Set the azimuth of the light source.
+     * @param azimuth The azimuth of the light source, between 0 and 360.0
+     * @see azimuth()
      */
     void setAzimuth( double azimuth ) { mLightAzimuth = azimuth; }
 
     /**
      * @brief Set the altitude of the light source
-     * @param altitude The altitude
+     * @param altitude the altitude
+     * @see altitude()
      */
     void setAltitude( double altitude ) { mLightAngle = altitude; }
 
     /**
-     * @brief Set the Z factor of the result image.
-     * @param zfactor The z factor.
+     * @brief Set the Z scaling factor of the result image.
+     * @param zfactor The z factor
+     * @see zFactor()
      */
     void setZFactor( double zfactor ) { mZFactor = zfactor; }
 
-    /**
-     * @brief Set Is Multi Directional
-     * @param isMultiDirectional Is multi directional
+    /** Sets whether to render using a multi-directional hillshade algorithm.
+     * @param isMultiDirectional set to true to use multi directional rendering
+     * @see multiDirectional()
      */
-    void setMultiDirectional( bool isMultiDirectional ){ mMultiDirectional = isMultiDirectional; }
+    void setMultiDirectional( bool isMultiDirectional ) { mMultiDirectional = isMultiDirectional; }
 
   private:
     int mBand;
     double mZFactor;
     double mLightAngle;
     double mLightAzimuth;
-    bool   mMultiDirectional;
+    bool mMultiDirectional;
 
     /** Calculates the first order derivative in x-direction according to Horn (1981)*/
     double calcFirstDerX( double x11, double x21, double x31, double x12, double x22, double x32, double x13, double x23, double x33 , double cellsize );

diff --git a/src/gui/raster/qgshillshaderendererwidget.cpp b/src/gui/raster/qgshillshaderendererwidget.cpp
@@ -65,7 +65,7 @@ QgsHillshadeRendererWidget::QgsHillshadeRendererWidget( QgsRasterLayer *layer, c
   connect( mLightAzimuth, SIGNAL( valueChanged( double ) ), this, SLOT( on_mLightAzimuth_updated( double ) ) );
   connect( mLightAzimuthDial, SIGNAL( valueChanged( int ) ), this, SLOT( on_mLightAzimuthDail_updated( int ) ) );
   connect( mZFactor, SIGNAL( valueChanged( double ) ), this, SIGNAL( widgetChanged() ) );
-  connect( mMultiDirection, SIGNAL( stateChanged( int )), this, SIGNAL( widgetChanged() ) );
+  connect( mMultiDirection, SIGNAL( toggled( bool ) ), this, SIGNAL( widgetChanged() ) );
 
   QgsBilinearRasterResampler* zoomedInResampler = new QgsBilinearRasterResampler();
   layer->resampleFilter()->setZoomedInResampler( zoomedInResampler );
@@ -126,9 +126,9 @@ void QgsHillshadeRendererWidget::setZFactor( double zfactor )
   mZFactor->setValue( zfactor );
 }
 
-void QgsHillshadeRendererWidget::setMultiDirectional(bool isMultiDirectional )
+void QgsHillshadeRendererWidget::setMultiDirectional( bool isMultiDirectional )
 {
-    mMultiDirection->setChecked( isMultiDirectional );
+  mMultiDirection->setChecked( isMultiDirectional );
 }
 
 void QgsHillshadeRendererWidget::on_mLightAzimuth_updated( double value )
@@ -166,5 +166,5 @@ double QgsHillshadeRendererWidget::zFactor() const
 
 bool QgsHillshadeRendererWidget::multiDirectional() const
 {
-    return mMultiDirection->isChecked();
+  return mMultiDirection->isChecked();
 }