QGIS/python/core/effects/qgsimageoperation.sip

/** \ingroup core
 * \class QgsImageOperation
 * \brief Contains operations and filters which apply to QImages
 *
 * A set of optimised pixel manipulation operations and filters which can be applied
 * to QImages. All operations only apply to ARGB32 format images, and it is left up
 * to the calling procedure to ensure that any passed images are of the correct
 * format.
 *
 * Operations are written to either modify an image in place or return a new image, depending
 * on which is faster for the particular operation.
 *
 * \note Added in version 2.7
 */
class QgsImageOperation
{
%TypeHeaderCode
#include <qgsimageoperation.h>
%End

  public:

    /** Modes for converting a QImage to grayscale
     */
    enum GrayscaleMode
    {
      GrayscaleLightness, /*!< keep the lightness of the color, drops the saturation */
      GrayscaleLuminosity, /*!< grayscale by perceptual luminosity (weighted sum of color RGB components) */
      GrayscaleAverage, /*!< grayscale by taking average of color RGB components */
      GrayscaleOff /*!< no change */
    };

    /** Flip operation types
     */
    enum FlipType
    {
      FlipHorizontal, /*!< flip the image horizontally */
      FlipVertical /*!< flip the image vertically */
    };

    /** Convert a QImage to a grayscale image. Alpha channel is preserved.
     * @param image QImage to convert
     * @param mode mode to use during grayscale conversion
     */
    static void convertToGrayscale( QImage &image, const GrayscaleMode mode = GrayscaleLuminosity );

    /** Alter the brightness or contrast of a QImage.
     * @param image QImage to alter
     * @param brightness brightness value, in the range -255 to 255. A brightness value of 0 indicates
     * no change to brightness, a negative value will darken the image, and a positive value will brighten
     * the image.
     * @param contrast contrast value. Must be a positive or zero value. A value of 1.0 indicates no change
     * to the contrast, a value of 0 represents an image with 0 contrast, and a value > 1.0 will increase the
     * contrast of the image.
     */
    static void adjustBrightnessContrast( QImage &image, const int brightness, const double contrast );

    /** Alter the hue or saturation of a QImage.
     * @param image QImage to alter
     * @param saturation double between 0 and 2 inclusive, where 0 = desaturate and 1.0 = no change
     * @param colorizeColor color to use for colorizing image. Set to an invalid QColor to disable
     * colorization.
     * @param colorizeStrength double between 0 and 1, where 0 = no colorization and 1.0 = full colorization
     */
    static void adjustHueSaturation( QImage &image, const double saturation, const QColor& colorizeColor = QColor(),
                                     const double colorizeStrength = 1.0 );

    /** Multiplies opacity of image pixel values by a factor.
     * @param image QImage to alter
     * @param factor factor to multiple pixel's opacity by
     */
    static void multiplyOpacity( QImage &image, const double factor );

    /** Overlays a color onto an image. This operation retains the alpha channel of the
     * original image, but replaces all image pixel colors with the specified color.
     * @param image QImage to alter
     * @param color color to overlay (any alpha component of the color is ignored)
     */
    static void overlayColor( QImage &image, const QColor& color );

    /** Struct for storing properties of a distance transform operation*/
    struct DistanceTransformProperties
    {
      /** Set to true to perform the distance transform on transparent pixels
       * in the source image, set to false to perform the distance transform
       * on opaque pixels
       */
      bool shadeExterior;
      /** Set to true to automatically calculate the maximum distance in the
       * transform to use as the spread value
       */
      bool useMaxDistance;
      /** Maximum distance (in pixels) for the distance transform shading to
       * spread
       */
      double spread;
      /** Color ramp to use for shading the distance transform
       */
      QgsColorRamp* ramp;
    };

    /** Performs a distance transform on the source image and shades the result
     * using a color ramp.
     * @param image QImage to alter
     * @param properties DistanceTransformProperties object with parameters
     * for the distance transform operation
     */
    static void distanceTransform( QImage &image, const QgsImageOperation::DistanceTransformProperties& properties );

    /** Performs a stack blur on an image. Stack blur represents a good balance between
     * speed and blur quality.
     * @param image QImage to blur
     * @param radius blur radius in pixels, maximum value of 16
     * @param alphaOnly set to true to blur only the alpha component of the image
     * @note for fastest operation, ensure the source image is ARGB32_Premultiplied if
     * alphaOnly is set to false, or ARGB32 if alphaOnly is true
     */
    static void stackBlur( QImage &image, const int radius, const bool alphaOnly = false );

    /** Performs a gaussian blur on an image. Gaussian blur is slower but results in a high
     * quality blur.
     * @param image QImage to blur
     * @param radius blur radius in pixels
     * @returns blurred image
     * @note for fastest operation, ensure the source image is ARGB32_Premultiplied
     */
    static QImage* gaussianBlur( QImage &image, const int radius ) /Factory/;

    /** Flips an image horizontally or vertically
     * @param image QImage to flip
     * @param type type of flip to perform (horizontal or vertical)
     */
    static void flipImage( QImage &image, FlipType type );

    /** Calculates the non-transparent region of an image.
     * @param image source image
     * @param minSize minimum size for returned region, if desired. If the
     * non-transparent region of the image is smaller than this minimum size,
     * it will be centered in the returned rectangle.
     * @param center return rectangle will be centered on the center of the original image if set to true
     * @note added in QGIS 2.9
     * @see cropTransparent
     */
    static QRect nonTransparentImageRect( const QImage & image, QSize minSize = QSize(), bool center = false );

    /** Crop any transparent border from around an image.
     * @param image source image
     * @param minSize minimum size for cropped image, if desired. If the
     * cropped image is smaller than the minimum size, it will be centered
     * in the returned image.
     * @param center cropped image will be centered on the center of the original image if set to true
     * @note added in QGIS 2.9
     */
    static QImage cropTransparent( const QImage & image, QSize minSize = QSize(), bool center = false );

};