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>

