NAME

       "Convert::Color" - color space conversions and named lookups

SYNOPSIS

        use Convert::Color;

        my $color = Convert::Color->new( 'hsv:76,0.43,0.89' );

        my ( $red, $green, $blue ) = $color->rgb;

        # GTK uses 16-bit values
        my $gtk_col = Gtk2::Gdk::Color->new( $color->as_rgb16->rgb16 );

        # HTML uses #rrggbb in hex
        my $html = '<td bgcolor="#' . $color->as_rgb8->hex . '">';

DESCRIPTION

       This module provides conversions between commonly used ways to express colors.  It
       provides conversions between color spaces such as RGB and HSV, and it provides ways to
       look up colors by a name.

       This class provides a base for subclasses which represent particular color values in
       particular spaces. The base class provides methods to represent the color in a few
       convenient forms, though subclasses may provide more specific details for the space in
       question.

       For more detail, read the documentation on these classes; namely:

       •   Convert::Color::RGB - red/green/blue as floats between 0 and 1

       •   Convert::Color::RGB8 - red/green/blue as 8-bit integers

       •   Convert::Color::RGB16 - red/green/blue as 16-bit integers

       •   Convert::Color::HSV - hue/saturation/value

       •   Convert::Color::HSL - hue/saturation/lightness

       •   Convert::Color::CMY - cyan/magenta/yellow

       •   Convert::Color::CMYK - cyan/magenta/yellow/key (blackness)

       The following classes are subclasses of one of the above, which provide a way to access
       predefined colors by names:

       •   Convert::Color::VGA - named lookup for the basic VGA colors

       •   Convert::Color::X11 - named lookup of colors from X11's rgb.txt

CONSTRUCTOR

   $color = Convert::Color->new( STRING )
       Return a new value to represent the color specified by the string. This string should be
       prefixed by the name of the color space to which it applies. For example

        rgb:RED,GREEN,BLUE
        rgb8:RRGGBB
        rgb16:RRRRGGGGBBBB
        hsv:HUE,SAT,VAL
        hsl:HUE,SAT,LUM
        cmy:CYAN,MAGENTA,YELLOW
        cmyk:CYAN,MAGENTA,YELLOW,KEY

        vga:NAME
        vga:INDEX

        x11:NAME

       For more detail, see the constructor of the color space subclass in question.

METHODS

   ( $red, $green, $blue ) = $color->rgb
       Returns the individual red, green and blue color components of the color value. For RGB
       values, this is done directly. For values in other spaces, this is done by first
       converting them to an RGB value using their "to_rgb()" method.

COLOR SPACE CONVERSIONS

       Cross-conversion between color spaces is provided by the "convert_to()" method, assisted
       by helper methods in the two color space classes involved.

       When converting $color from color space SRC to color space DEST, the following operations
       are attemped, in this order. SRC and DEST refer to the names of the color spaces, e.g.
       "rgb".

       1.  If SRC and DEST are equal, return $color as it stands.

       2.  If the SRC space's class provides a "convert_to_DEST" method, use it.

       3.  If the DEST space's class provides a "new_from_SRC" constructor, call it and pass
           $color.

       4.  If the DEST space's class provides a "new_rgb" constructor, convert $color to
           red/green/blue components then call it.

       5.  If none of these operations worked, then throw an exception.

       These functions may be called in the following ways:

        $other = $color->convert_to_DEST()
        $other = Dest::Class->new_from_SRC( $color )
        $other = Dest::Class->new_rgb( $color->rgb )

   $other = $color->convert_to( $space )
       Attempt to convert the color into its representation in the given space. See above for the
       various ways this may be achieved.

       If the relevant subclass has already been loaded (either explicitly, or implicitly by
       either the "new" or "convert_to" methods), then a specific conversion method will be
       installed in the class.

        $other = $color->as_$space

       Methods of this form are currently "AUTOLOAD"ed if they do not yet exist, but this feature
       should not be relied upon - see below.

AUTOLOADED CONVERSION METHODS

       This class provides "AUTOLOAD" and "can" behaviour which automatically constructs
       conversion methods. The following method calls are identical:

        $color->convert_to('rgb')
        $color->as_rgb

       The generated method will be stored in the package, so that future calls will not have the
       AUTOLOAD overhead.

       This feature is deprecated and should not be relied upon, due to the delicate nature of
       "AUTOLOAD".

OTHER METHODS

       As well as the above, it is likely the subclass will provide accessors to directly obtain
       the components of its representation in the specific space.  For more detail, see the
       documentation for the specific subclass in question.

SUBCLASS METHODS

       This base class is intended to be subclassed to provide more color spaces.

   $class->register_color_space( $space )
       A subclass should call this method to register itself as a named color space.

   $class->register_palette( %args )
       A subclass that provides a fixed set of color values should call this method, to set up
       automatic conversions that look for the closest match within the set. This conversion
       process is controlled by the %args:

       enumerate => STRING or CODE
               A method name or anonymous CODE reference which will be used to generate the list
               of color values.

       enumerate_once => STRING or CODE
               As per "enumerate", but will be called only once and the results cached.

       This method creates a new class method on the calling package, called "closest_to".

       $color = $pkg->closest_to( $orig, $space )

       Returns the color in the space closest to the given value. The distance is measured in the
       named space; defaulting to "rgb" if this is not provided.

       In the case of a tie, where two or more colors have the same distance from the target, the
       first one will be chosen.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>