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
new
$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
rgb
( $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 )
convert_to
$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 AUTOLOADed 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.
register_color_space
$class->register_color_space( $space )
A subclass should call this method to register itself as a named color
space.
register_palette
$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.
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>