qgscolorramp.h

/***************************************************************************
    qgscolorramp.h
    ---------------------
    begin                : November 2009
    copyright            : (C) 2009 by Martin Dobias
    email                : wonder dot sk at gmail dot com
 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef QGSCOLORRAMP_H
#define QGSCOLORRAMP_H

#include <QColor>
#include <QGradient>
#include "qgis.h"
#include "qgscolorscheme.h"

/** \ingroup core
 * \class QgsColorRamp
 * \brief Abstract base class for color ramps
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsColorRamp
{
  public:

    virtual ~QgsColorRamp() {}

    /** Returns number of defined colors, or -1 if undefined
     */
    virtual int count() const = 0;

    /** Returns relative value between [0,1] of color at specified index
     */
    virtual double value( int index ) const = 0;

    /** Returns the color corresponding to a specified value.
     * @param value value between [0, 1] inclusive
     * @returns color for value
     */
    virtual QColor color( double value ) const = 0;

    /** Returns a string representing the color ramp type.
     */
    virtual QString type() const = 0;

    /** Creates a clone of the color ramp.
     */
    virtual QgsColorRamp* clone() const = 0;

    /** Returns a string map containing all the color ramp's properties.
     */
    virtual QgsStringMap properties() const = 0;
};

/** \ingroup core
 * \class QgsGradientStop
 * \brief Represents a color stop within a QgsGradientColorRamp color ramp.
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsGradientStop
{
  public:

    /** Constructor for QgsGradientStop
     * @param offset positional offset for stop, between 0 and 1.0
     * @param color color for stop
     */
    QgsGradientStop( double offset, const QColor& color )
        : offset( offset )
        , color( color )
    { }

    //! Relative positional offset, between 0 and 1
    double offset;
    //! Gradient color at stop
    QColor color;

    bool operator==( const QgsGradientStop& other ) const
    {
      return other.color == color && qgsDoubleNear( other.offset, offset );
    }
};

//! List of gradient stops
typedef QList<QgsGradientStop> QgsGradientStopsList;

#define DEFAULT_GRADIENT_COLOR1 QColor(0,0,255)
#define DEFAULT_GRADIENT_COLOR2 QColor(0,255,0)

/** \ingroup core
 * \class QgsGradientColorRamp
 * \brief Gradient color ramp, which smoothly interpolates between two colors and also
 * supports optional extra color stops.
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsGradientColorRamp : public QgsColorRamp
{
  public:

    /** Constructor for QgsGradientColorRamp
     * @param color1 start color, corresponding to a position of 0.0
     * @param color2 end color, corresponding to a position of 1.0
     * @param discrete set to true for discrete interpolation instead of smoothly
     * interpolating between colors
     * @param stops optional list of additional color stops
     */
    QgsGradientColorRamp( const QColor& color1 = DEFAULT_GRADIENT_COLOR1,
                          const QColor& color2 = DEFAULT_GRADIENT_COLOR2,
                          bool discrete = false,
                          const QgsGradientStopsList& stops = QgsGradientStopsList() );

    //! Creates a new QgsColorRamp from a map of properties
    static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );

    virtual int count() const override { return mStops.count() + 2; }
    virtual double value( int index ) const override;
    virtual QColor color( double value ) const override;
    virtual QString type() const override { return "gradient"; }
    virtual QgsGradientColorRamp* clone() const override;
    virtual QgsStringMap properties() const override;

    /** Returns the gradient start color.
     * @see setColor1()
     * @see color2()
     */
    QColor color1() const { return mColor1; }

    /** Returns the gradient end color.
     * @see setColor2()
     * @see color1()
     */
    QColor color2() const { return mColor2; }

    /** Sets the gradient start color.
     * @param color start color
     * @see color1()
     * @see setColor2()
     */
    void setColor1( const QColor& color ) { mColor1 = color; }

    /** Sets the gradient end color.
     * @param color end color
     * @see color2()
     * @see setColor1()
     */
    void setColor2( const QColor& color ) { mColor2 = color; }

    /** Returns true if the gradient is using discrete interpolation, rather than
     * smoothly interpolating between colors.
     * @see setDiscrete()
     */
    bool isDiscrete() const { return mDiscrete; }

    /** Sets whether the gradient should use discrete interpolation, rather than
     * smoothly interpolating between colors.
     * @param discrete set to true to use discrete interpolation
     * @see convertToDiscrete()
     * @see isDiscrete()
     */
    void setDiscrete( bool discrete ) { mDiscrete = discrete; }

    /** Converts a gradient with existing color stops to or from discrete
     * interpolation.
     * @param discrete set to true to convert the gradient stops to discrete,
     * or false to convert them to smooth interpolation
     * @see isDiscrete()
     */
    void convertToDiscrete( bool discrete );

    /** Sets the list of intermediate gradient stops for the ramp.
     * @param stops list of stops. Any existing color stops will be replaced. The stop
     * list will be automatically reordered so that stops are listed in ascending offset
     * order.
     * @see stops()
     */
    void setStops( const QgsGradientStopsList& stops );

    /** Returns the list of intermediate gradient stops for the ramp.
     * @see setStops()
     */
    QgsGradientStopsList stops() const { return mStops; }

    /** Returns any additional info attached to the gradient ramp (eg authorship notes)
     * @see setInfo()
     */
    QgsStringMap info() const { return mInfo; }

    /** Sets additional info to attach to the gradient ramp (eg authorship notes)
     * @param info map of string info to attach
     * @see info()
     */
    void setInfo( const QgsStringMap& info ) { mInfo = info; }

    /** Copy color ramp stops to a QGradient
     * @param gradient gradient to copy stops into
     * @param alpha alpha multiplier. Opacity of colors will be multiplied
     * by this factor before adding to the gradient.
     * @note added in 2.1
     */
    void addStopsToGradient( QGradient* gradient, double alpha = 1 );

  protected:
    QColor mColor1;
    QColor mColor2;
    bool mDiscrete;
    QgsGradientStopsList mStops;
    QgsStringMap mInfo;
};

#define DEFAULT_RANDOM_COUNT   10
#define DEFAULT_RANDOM_HUE_MIN 0
#define DEFAULT_RANDOM_HUE_MAX 359
#define DEFAULT_RANDOM_VAL_MIN 200
#define DEFAULT_RANDOM_VAL_MAX 240
#define DEFAULT_RANDOM_SAT_MIN 100
#define DEFAULT_RANDOM_SAT_MAX 240

/** \ingroup core
 * \class QgsLimitedRandomColorRamp
 * \brief Constrained random color ramp, which returns random colors based on preset parameters.
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsLimitedRandomColorRamp : public QgsColorRamp
{
  public:

    /** Constructor for QgsLimitedRandomColorRamp
     * @param count number of colors in ramp
     * @param hueMin minimum hue
     * @param hueMax maximum hue
     * @param satMin minimum saturation
     * @param satMax maximum saturation
     * @param valMin minimum color value
     * @param valMax maximum color value
     */
    QgsLimitedRandomColorRamp( int count = DEFAULT_RANDOM_COUNT,
                               int hueMin = DEFAULT_RANDOM_HUE_MIN, int hueMax = DEFAULT_RANDOM_HUE_MAX,
                               int satMin = DEFAULT_RANDOM_SAT_MIN, int satMax = DEFAULT_RANDOM_SAT_MAX,
                               int valMin = DEFAULT_RANDOM_VAL_MIN, int valMax = DEFAULT_RANDOM_VAL_MAX );

    /** Returns a new QgsLimitedRandomColorRamp color ramp created using the properties encoded in a string
     * map.
     * @param properties color ramp properties
     * @see properties()
     */
    static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );

    virtual double value( int index ) const override;
    virtual QColor color( double value ) const override;
    virtual QString type() const override { return "random"; }
    virtual QgsLimitedRandomColorRamp* clone() const override;
    virtual QgsStringMap properties() const override;
    int count() const override { return mCount; }

    /** Get a list of random colors
     * @note added in 2.4
     */
    static QList<QColor> randomColors( int count,
                                       int hueMax = DEFAULT_RANDOM_HUE_MAX, int hueMin = DEFAULT_RANDOM_HUE_MIN,
                                       int satMax = DEFAULT_RANDOM_SAT_MAX, int satMin = DEFAULT_RANDOM_SAT_MIN,
                                       int valMax = DEFAULT_RANDOM_VAL_MAX, int valMin = DEFAULT_RANDOM_VAL_MIN );

    /** Must be called after changing the properties of the color ramp
     * to regenerate the list of random colors.
     */
    void updateColors();

    /** Returns the minimum hue for generated colors
     * @see setHueMin()
     */
    int hueMin() const { return mHueMin; }

    /** Returns the maximum hue for generated colors
     * @see setHueMax()
     */
    int hueMax() const { return mHueMax; }

    /** Returns the minimum saturation for generated colors
     * @see setSatMin()
     */
    int satMin() const { return mSatMin; }

    /** Returns the maximum saturation for generated colors
     * @see setSatMax()
     */
    int satMax() const { return mSatMax; }

    /** Returns the minimum value for generated colors
     * @see setValMin()
     */
    int valMin() const { return mValMin; }

    /** Returns the maximum value for generated colors
     * @see setValMax()
     */
    int valMax() const { return mValMax; }

    /** Sets the number of colors contained in the ramp.
     */
    void setCount( int val ) { mCount = val; }

    /** Sets the minimum hue for generated colors
     * @see hueMin()
     */
    void setHueMin( int val ) { mHueMin = val; }

    /** Sets the maximum hue for generated colors
     * @see hueMax()
     */
    void setHueMax( int val ) { mHueMax = val; }

    /** Sets the minimum saturation for generated colors
     * @see satMin()
     */
    void setSatMin( int val ) { mSatMin = val; }

    /** Sets the maximum saturation for generated colors
     * @see satMax()
     */
    void setSatMax( int val ) { mSatMax = val; }

    /** Sets the minimum value for generated colors
     * @see valMin()
     */
    void setValMin( int val ) { mValMin = val; }

    /** Sets the maximum value for generated colors
     * @see valMax()
     */
    void setValMax( int val ) { mValMax = val; }

  protected:
    int mCount;
    int mHueMin, mHueMax, mSatMin, mSatMax, mValMin, mValMax;
    QList<QColor> mColors;
};

/** \ingroup core
 * \class QgsRandomColorRamp
 * \brief Totally random color ramp. Returns colors generated at random, but constrained
 * to some hardcoded saturation and value ranges to prevent ugly color generation.
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsRandomColorRamp: public QgsColorRamp
{
  public:
    QgsRandomColorRamp();
    ~QgsRandomColorRamp();

    int count() const override;

    double value( int index ) const override;

    QColor color( double value ) const override;

    /** Sets the desired total number of unique colors for the resultant ramp. Calling
     * this method pregenerates a set of visually distinct colors which are returned
     * by subsequent calls to color().
     * @param colorCount number of unique colors
     * @note added in QGIS 2.5
     */
    virtual void setTotalColorCount( const int colorCount );

    QString type() const override;

    QgsRandomColorRamp* clone() const override;

    QgsStringMap properties() const override;

  protected:

    int mTotalColorCount;
    QList<QColor> mPrecalculatedColors;

};


/** \ingroup core
 * \class QgsPresetSchemeColorRamp
 * \brief A scheme based color ramp consisting of a list of predefined colors.
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsPresetSchemeColorRamp : public QgsColorRamp, public QgsColorScheme
{
  public:

    /** Constructor for QgsPresetSchemeColorRamp.
     * @param colors list of colors in ramp
     */
    QgsPresetSchemeColorRamp( const QList< QColor >& colors = QList< QColor >() );

    /** Constructor for QgsPresetColorRamp.
     * @param colors list of named colors in ramp
     * @note not available in Python bindings - use setColors instead
     */
    QgsPresetSchemeColorRamp( const QgsNamedColorList& colors );

    /** Returns a new QgsPresetSchemeColorRamp color ramp created using the properties encoded in a string
     * map.
     * @param properties color ramp properties
     * @see properties()
     */
    static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );

    /** Sets the list of colors used by the ramp.
     * @param colors list of colors
     * @see colors()
     */
    bool setColors( const QgsNamedColorList& colors, const QString& = QString(), const QColor& = QColor() ) override { mColors = colors; return true; }

    /** Returns the list of colors used by the ramp.
     * @see setColors()
     */
    QList< QColor > colors() const;

    // QgsColorRamp interface
    virtual double value( int index ) const override;
    virtual QColor color( double value ) const override;
    virtual QString type() const override { return "preset"; }
    virtual QgsPresetSchemeColorRamp* clone() const override;
    virtual QgsStringMap properties() const override;
    int count() const override;

    // QgsColorScheme interface
    QString schemeName() const override { return "preset"; }
    QgsNamedColorList fetchColors( const QString &context = QString(),
                                   const QColor &baseColor = QColor() ) override;
    bool isEditable() const override { return true; }

  private:

    QgsNamedColorList mColors;
};


#define DEFAULT_COLORBREWER_SCHEMENAME "Spectral"
#define DEFAULT_COLORBREWER_COLORS     5

/** \ingroup core
 * \class QgsColorBrewerColorRamp
 * \brief Color ramp utilising "Color Brewer" preset color schemes.
 * \note added in QGIS 3.0
 */
class CORE_EXPORT QgsColorBrewerColorRamp : public QgsColorRamp
{
  public:

    /** Constructor for QgsColorBrewerColorRamp
     * @param schemeName color brewer scheme name
     * @param colors number of colors in ramp
     */
    QgsColorBrewerColorRamp( const QString& schemeName = DEFAULT_COLORBREWER_SCHEMENAME,
                             int colors = DEFAULT_COLORBREWER_COLORS );

    /** Returns a new QgsColorBrewerColorRamp color ramp created using the properties encoded in a string
     * map.
     * @param properties color ramp properties
     * @see properties()
     */
    static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );

    virtual double value( int index ) const override;
    virtual QColor color( double value ) const override;
    virtual QString type() const override { return "colorbrewer"; }
    virtual QgsColorBrewerColorRamp* clone() const override;
    virtual QgsStringMap properties() const override;
    virtual int count() const override { return mColors; }

    /** Returns the name of the color brewer color scheme.
     * @see setSchemeName()
     */
    QString schemeName() const { return mSchemeName; }

    /** Returns the number of colors in the ramp.
     * @see setColors()
     */
    int colors() const { return mColors; }

    /** Sets the name of the color brewer color scheme.
     * @param schemeName scheme name, must match a valid color brewer scheme name
     * @see schemeName()
     * @see listSchemeNames()
     */
    void setSchemeName( const QString& schemeName ) { mSchemeName = schemeName; loadPalette(); }

    /** Sets the number of colors in the ramp.
     * @param colors number of colors. Must match a valid value for the scheme,
     * which can be retrieved using listSchemeVariants()
     * @see colors()
     */
    void setColors( int colors ) { mColors = colors; loadPalette(); }

    /** Returns a list of all valid color brewer scheme names.
     * @see listSchemeVariants()
     */
    static QStringList listSchemeNames();

    /** Returns a list of the valid variants (numbers of colors) for a specified
     * color brewer scheme name
     * @param schemeName color brewer scheme name
     * @see listSchemeNames()
     */
    static QList<int> listSchemeVariants( const QString& schemeName );

  protected:

    //! Generates the scheme using the current name and number of colors
    void loadPalette();

    QString mSchemeName;
    int mColors;
    QList<QColor> mPalette;
};


#define DEFAULT_CPTCITY_SCHEMENAME "cb/div/BrBG_" //change this
#define DEFAULT_CPTCITY_VARIANTNAME "05"

/** \ingroup core
 * \class QgsCptCityColorRamp
 */
class CORE_EXPORT QgsCptCityColorRamp : public QgsGradientColorRamp
{
  public:
    QgsCptCityColorRamp( const QString& schemeName = DEFAULT_CPTCITY_SCHEMENAME,
                         const QString& variantName = DEFAULT_CPTCITY_VARIANTNAME,
                         bool doLoadFile = true );
    QgsCptCityColorRamp( const QString& schemeName, const QStringList& variantList,
                         const QString& variantName = QString(), bool doLoadFile = true );

    static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );

    virtual QString type() const override { return "cpt-city"; }

    virtual QgsCptCityColorRamp* clone() const override;
    void copy( const QgsCptCityColorRamp* other );
    QgsGradientColorRamp* cloneGradientRamp() const;

    virtual QgsStringMap properties() const override;

    QString schemeName() const { return mSchemeName; }
    QString variantName() const { return mVariantName; }
    QStringList variantList() const { return mVariantList; }

    /* lazy loading - have to call loadPalette() explicitly */
    void setSchemeName( const QString& schemeName ) { mSchemeName = schemeName; mFileLoaded = false; }
    void setVariantName( const QString& variantName ) { mVariantName = variantName; mFileLoaded = false; }
    void setVariantList( const QStringList& variantList ) { mVariantList = variantList; }
    void setName( const QString& schemeName, const QString& variantName = "", const QStringList& variantList = QStringList() )
    { mSchemeName = schemeName; mVariantName = variantName; mVariantList = variantList; mFileLoaded = false; }

    void loadPalette() { loadFile(); }
    bool hasMultiStops() const { return mMultiStops; }

    QString fileName() const;
    bool loadFile();
    bool fileLoaded() const { return mFileLoaded; }

    QString copyingFileName() const;
    QString descFileName() const;
    QgsStringMap copyingInfo() const;

  protected:

    QString mSchemeName;
    QString mVariantName;
    QStringList mVariantList;
    bool mFileLoaded;
    bool mMultiStops;
};


#endif