Magick++ API: Working with Color

# Magick::Color

Color is the base color class in Magick++. It is a simple container class for the pixel red, green, blue, and alpha values scaled to fit ImageMagick's Quantum size. Normally users will instantiate a class derived from Color which supports the color model that fits the needs of the application. The Color class may be constructed directly from an SVG-style color string.

#### Quantum

The base type used to represent color samples in ImageMagick is the Quantum type. Pixels are represented by a structure of Quantum values. For example, an RGB pixel contains red, green, and blue quantums, while an RGBA pixel contains red, green, blue, and opacity quantums. The maximum value that a Quantum can attain is specified by a constant value represented by the MaxRGB define, which is itself determined by the number of bits in a Quantum. The QuantumDepth build option determines the number of bits in a Quantum.

#### Quantum

Quantum is the internal representation of a pixel in ImageMagick. ImageMagick may be compiled to support 32, 64, or 128 bit pixels of type Quantum. This is controlled by the value of the QuantumDepth define. The default is 32 bit pixels (QuantumDepth=8), which provides the best performance and the least resource consumption. If additional color precision or range is desired, then ImageMagick may be compiled with QuantumDepth=16 or QuantumDepth=32. The following table shows the relationship between QuantumDepth, the type of Quantum, and the overall Quantum size.

Effect Of QuantumDepth Values

QuantumDepth | Quantum Typedef | Quantum Size
8 | unsigned char | 32 bits
16 | unsigned short | 64 bits
32 | unsigned int | 128 bits

### Color Class

The Color base class is not intended to be used directly. Normally a user will construct a derived class or inherit from this class. Color arguments are must be scaled to fit the Quantum size. The Color class contains a pointer to a Quantum, which may be allocated by the Color class, or may refer to an existing pixel in an image.

An alternate way to construct the class is via an SVG-compatible color specification string (e.g. Color("red") or Color ("#FF0000")). Since the class may be constructed from a string, convenient strings may be passed in place of an explicit Color object in methods which accept a reference to Color. Color may also be converted to a std::string for convenience in user interfaces, and for saving settings to a text file.

class Color { public: Color ( Quantum red_, Quantum green_, Quantum blue_ ); Color ( Quantum red_, Quantum green_, Quantum blue_, Quantum alpha_ ); Color ( const std::string &svgColor_ ); Color ( const char * svgColor_ ); Color ( void ); virtual ~Color ( void ); Color ( const Color & color_ ); // Red color (range 0 to MaxRGB) void redQuantum ( Quantum red_ ); Quantum redQuantum ( void ) const; // Green color (range 0 to MaxRGB) void greenQuantum ( Quantum green_ ); Quantum greenQuantum ( void ) const; // Blue color (range 0 to MaxRGB) void blueQuantum ( Quantum blue_ ); Quantum blueQuantum ( void ) const; // Alpha level (range OpaqueOpacity=0 to TransparentOpacity=MaxRGB) void alphaQuantum ( Quantum alpha_ ); Quantum alphaQuantum ( void ) const; // Scaled (to 1.0) version of alpha for use in sub-classes // (range opaque=0 to transparent=1.0) void alpha ( double alpha_ ); double alpha ( void ) const; // Does object contain valid color? void isValid ( bool valid_ ); bool isValid ( void ) const; // Set color via SVG color specification string const Color& operator= ( const std::string & svgColor_ ); const Color& operator= ( const char * svgColor_ ); // Assignment operator Color& operator= ( const Color& color_ ); // Return SVG color specification string /* virtual */ operator std::string() const; // Return ImageMagick Quantum operator Quantum() const; // Construct color via ImageMagick Quantum Color ( const Quantum &color_ ); // Set color via ImageMagick Quantum const Color& operator= ( Quantum &color_ ); };

Color Derived Classes

ColorRGB | Representation of RGB color with red, green, and blue specified as ratios (0 to 1)
ColorGray | Representation of grayscale sRGB color (equal parts red, green, and blue) specified as a ratio (0 to 1)
ColorMono | Representation of a black/white color (true/false)
ColorYUV | Representation of a color in the YUV colorspace

### ColorRGB

Representation of an sRGB color. All color arguments have a valid range of 0.0 - 1.0.

    class ColorRGB : public Color
    {
      public:
        ColorRGB ( double red_, double green_, double blue_ );
        ColorRGB ( void );
        ColorRGB ( const Color & color_ );
        /* virtual */  ~ColorRGB ( void );

        void           red ( double red_ );
        double         red ( void ) const;

        void           green ( double green_ );
        double         green ( void ) const;

        void           blue ( double blue_ );
        double         blue ( void ) const;

        // Assignment operator from base class
        ColorRGB& operator= ( const Color& color_ );
    };

### ColorGray

Representation of a grayscale color (in linear colorspace). Grayscale is simply RGB with equal parts of red, green, and blue. All double arguments have a valid range of 0.0 - 1.0.

    class ColorGray : public Color
    {
      public:
        ColorGray ( double shade_ );
        ColorGray ( void );
        ColorGray ( const Color & color_ );
        /* virtual */ ~ColorGray ();

        void           shade ( double shade_ );
        double         shade ( void ) const;

        // Assignment operator from base class
        ColorGray& operator= ( const Color& color_ );
    };

### ColorMono

Representation of a black/white pixel (in RGB colorspace). Color arguments are constrained to 'false' (black pixel) and 'true' (white pixel).

    class ColorMono : public Color
    {
      public:
        ColorMono ( bool mono_ );
        ColorMono ( void );
        ColorMono ( const Color & color_ );
        /* virtual */ ~ColorMono ();

        void           mono ( bool mono_ );
        bool           mono ( void ) const;

        // Assignment operator from base class
        ColorMono& operator= ( const Color& color_ );
    };

### ColorHSL

Representation of a color in Hue/Saturation/Luminosity (HSL) colorspace.

    class ColorHSL : public Color
    {
      public:
        ColorHSL ( double hue_, double saturation_, double luminosity_ );
        ColorHSL ( void );
        ColorHSL ( const Color & color_ );
        /* virtual */  ~ColorHSL ( );

        void           hue ( double hue_ );
        double         hue ( void ) const;

        void           saturation ( double saturation_ );
        double         saturation ( void ) const;

        void           luminosity ( double luminosity_ );
        double         luminosity ( void ) const;

        // Assignment operator from base class
        ColorHSL& operator= ( const Color& color_ );
    };

### ColorYUV

Representation of a color in YUV colorspace (used to encode color for television transmission).

Argument ranges:

  Y: 0.0 through 1.0
  U: -0.5 through 0.5
  V: -0.5 through 0.5

    class ColorYUV : public Color
    {
      public:
        ColorYUV ( double y_, double u_, double v_ );
        ColorYUV ( void );
        ColorYUV ( const Color & color_ );
        /* virtual */ ~ColorYUV ( void );

        void           u ( double u_ );
        double         u ( void ) const;

        void           v ( double v_ );
        double         v ( void ) const;

        void           y ( double y_ );
        double         y ( void ) const;

        // Assignment operator from base class
        ColorYUV& operator= ( const Color& color_ );
    };