1NAME
2 `Convert::Color' - color space conversions and named lookups
3
4SYNOPSIS
5 use Convert::Color;
6
7 my $color = Convert::Color->new( 'hsv:76,0.43,0.89' );
8
9 my ( $red, $green, $blue ) = $color->rgb;
10
11 # GTK uses 16-bit values
12 my $gtk_col = Gtk2::Gdk::Color->new( $color->as_rgb16->rgb16 );
13
14 # HTML uses #rrggbb in hex
15 my $html = '<td bgcolor="#' . $color->as_rgb8->hex . '">';
16
17DESCRIPTION
18 This module provides conversions between commonly used ways to express
19 colors. It provides conversions between color spaces such as RGB and
20 HSV, and it provides ways to look up colors by a name.
21
22 This class provides a base for subclasses which represent particular
23 color values in particular spaces. The base class provides methods to
24 represent the color in a few convenient forms, though subclasses may
25 provide more specific details for the space in question.
26
27 For more detail, read the documentation on these classes; namely:
28
29 * Convert::Color::RGB - red/green/blue as floats between 0 and 1
30
31 * Convert::Color::RGB8 - red/green/blue as 8-bit integers
32
33 * Convert::Color::RGB16 - red/green/blue as 16-bit integers
34
35 * Convert::Color::HSV - hue/saturation/value
36
37 * Convert::Color::HSL - hue/saturation/lightness
38
39 * Convert::Color::CMY - cyan/magenta/yellow
40
41 * Convert::Color::CMYK - cyan/magenta/yellow/key (blackness)
42
43 The following classes are subclasses of one of the above, which provide
44 a way to access predefined colors by names:
45
46 * Convert::Color::VGA - named lookup for the basic VGA colors
47
48 * Convert::Color::X11 - named lookup of colors from X11's rgb.txt
49
50CONSTRUCTOR
51 $color = Convert::Color->new( STRING )
52 Return a new value to represent the color specified by the string. This
53 string should be prefixed by the name of the color space to which it
54 applies. For example
55
56 rgb:RED,GREEN,BLUE
57 rgb8:RRGGBB
58 rgb16:RRRRGGGGBBBB
59 hsv:HUE,SAT,VAL
60 hsl:HUE,SAT,LUM
61 cmy:CYAN,MAGENTA,YELLOW
62 cmyk:CYAN,MAGENTA,YELLOW,KEY
63
64 vga:NAME
65 vga:INDEX
66
67 x11:NAME
68
69 For more detail, see the constructor of the color space subclass in
70 question.
71
72METHODS
73 ( $red, $green, $blue ) = $color->rgb
74 Returns the individual red, green and blue color components of the color
75 value. For RGB values, this is done directly. For values in other
76 spaces, this is done by first converting them to an RGB value using
77 their `to_rgb()' method.
78
79COLOR SPACE CONVERSIONS
80 Cross-conversion between color spaces is provided by the `convert_to()'
81 method, assisted by helper methods in the two color space classes
82 involved.
83
84 When converting `$color' from color space SRC to color space DEST, the
85 following operations are attemped, in this order. SRC and DEST refer to
86 the names of the color spaces, e.g. `rgb'.
87
88 1. If SRC and DEST are equal, return `$color' as it stands.
89
90 2. If the SRC space's class provides a `convert_to_DEST' method, use
91 it.
92
93 3. If the DEST space's class provides a `new_from_SRC' constructor,
94 call it and pass `$color'.
95
96 4. If the DEST space's class provides a `new_rgb' constructor, convert
97 `$color' to red/green/blue components then call it.
98
99 5. If none of these operations worked, then throw an exception.
100
101 These functions may be called in the following ways:
102
103 $other = $color->convert_to_DEST()
104 $other = Dest::Class->new_from_SRC( $color )
105 $other = Dest::Class->new_rgb( $color->rgb )
106
107 $other = $color->convert_to( $space )
108 Attempt to convert the color into its representation in the given space.
109 See above for the various ways this may be achieved.
110
111 If the relevant subclass has already been loaded (either explicitly, or
112 implicitly by either the `new' or `convert_to' methods), then a specific
113 conversion method will be installed in the class.
114
115 $other = $color->as_$space
116
117 Methods of this form are currently `AUTOLOAD'ed if they do not yet
118 exist, but this feature should not be relied upon - see below.
119
120AUTOLOADED CONVERSION METHODS
121 This class provides `AUTOLOAD' and `can' behaviour which automatically
122 constructs conversion methods. The following method calls are identical:
123
124 $color->convert_to('rgb')
125 $color->as_rgb
126
127 The generated method will be stored in the package, so that future calls
128 will not have the AUTOLOAD overhead.
129
130 This feature is deprecated and should not be relied upon, due to the
131 delicate nature of `AUTOLOAD'.
132
133OTHER METHODS
134 As well as the above, it is likely the subclass will provide accessors
135 to directly obtain the components of its representation in the specific
136 space. For more detail, see the documentation for the specific subclass
137 in question.
138
139SUBCLASS METHODS
140 This base class is intended to be subclassed to provide more color
141 spaces.
142
143 $class->register_color_space( $space )
144 A subclass should call this method to register itself as a named color
145 space.
146
147 $class->register_palette( %args )
148 A subclass that provides a fixed set of color values should call this
149 method, to set up automatic conversions that look for the closest match
150 within the set. This conversion process is controlled by the `%args':
151
152 enumerate => STRING or CODE
153 A method name or anonymous CODE reference which will be used to
154 generate the list of color values.
155
156 enumerate_once => STRING or CODE
157 As per `enumerate', but will be called only once and the results
158 cached.
159
160 This method creates a new class method on the calling package, called
161 `closest_to'.
162
163 $color = $pkg->closest_to( $orig, $space )
164 Returns the color in the space closest to the given value. The distance
165 is measured in the named space; defaulting to `rgb' if this is not
166 provided.
167
168 In the case of a tie, where two or more colors have the same distance
169 from the target, the first one will be chosen.
170
171AUTHOR
172 Paul Evans <leonerd@leonerd.org.uk>
173
174