Debian Codegraph @

README

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