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