1Convert::Color(3)     User Contributed Perl Documentation    Convert::Color(3)
2
3
4

NAME

6       "Convert::Color" - color space conversions and named lookups
7

SYNOPSIS

9          use Convert::Color;
10
11          my $color = Convert::Color->new( 'hsv:76,0.43,0.89' );
12
13          my ( $red, $green, $blue ) = $color->rgb;
14
15          # GTK uses 16-bit values
16          my $gtk_col = Gtk2::Gdk::Color->new( $color->as_rgb16->rgb16 );
17
18          # HTML uses #rrggbb in hex
19          my $html = '<td bgcolor="#' . $color->as_rgb8->hex . '">';
20

DESCRIPTION

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
26       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
31       For more detail, read the documentation on these classes; namely:
32
33       •   Convert::Color::RGB - red/green/blue as floats between 0 and 1
34
35       •   Convert::Color::RGB8 - red/green/blue as 8-bit integers
36
37       •   Convert::Color::RGB16 - red/green/blue as 16-bit integers
38
39       •   Convert::Color::HSV - hue/saturation/value
40
41       •   Convert::Color::HSL - hue/saturation/lightness
42
43       •   Convert::Color::CMY - cyan/magenta/yellow
44
45       •   Convert::Color::CMYK - cyan/magenta/yellow/key (blackness)
46
47       The following classes are subclasses of one of the above, which provide
48       a way to access predefined colors by names:
49
50       •   Convert::Color::VGA - named lookup for the basic VGA colors
51
52       •   Convert::Color::X11 - named lookup of colors from X11's rgb.txt
53

CONSTRUCTOR

55   new
56          $color = Convert::Color->new( STRING )
57
58       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
62          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
70          vga:NAME
71          vga:INDEX
72
73          x11:NAME
74
75       For more detail, see the constructor of the color space subclass in
76       question.
77

METHODS

79   rgb
80          ( $red, $green, $blue ) = $color->rgb
81
82       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

COLOR SPACE CONVERSIONS

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
92       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
96       1.  If SRC and DEST are equal, return $color as it stands.
97
98       2.  If the SRC space's class provides a "convert_to_DEST" method, use
99           it.
100
101       3.  If the DEST space's class provides a "new_from_SRC" constructor,
102           call it and pass $color.
103
104       4.  If the DEST space's class provides a "new_rgb" constructor, convert
105           $color to red/green/blue components then call it.
106
107       5.  If none of these operations worked, then throw an exception.
108
109       These functions may be called in the following ways:
110
111          $other = $color->convert_to_DEST()
112          $other = Dest::Class->new_from_SRC( $color )
113          $other = Dest::Class->new_rgb( $color->rgb )
114
115   convert_to
116          $other = $color->convert_to( $space )
117
118       Attempt to convert the color into its representation in the given
119       space. See above for the various ways this may be achieved.
120
121       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
125          $other = $color->as_$space
126
127       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

AUTOLOADED CONVERSION METHODS

131       This class provides "AUTOLOAD" and "can" behaviour which automatically
132       constructs conversion methods. The following method calls are
133       identical:
134
135          $color->convert_to('rgb')
136          $color->as_rgb
137
138       The generated method will be stored in the package, so that future
139       calls will not have the AUTOLOAD overhead.
140
141       This feature is deprecated and should not be relied upon, due to the
142       delicate nature of "AUTOLOAD".
143

OTHER METHODS

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

SUBCLASS METHODS

151       This base class is intended to be subclassed to provide more color
152       spaces.
153
154   register_color_space
155          $class->register_color_space( $space )
156
157       A subclass should call this method to register itself as a named color
158       space.
159
160   register_palette
161          $class->register_palette( %args )
162
163       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
167       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
171       enumerate_once => STRING or CODE
172               As per "enumerate", but will be called only once and the
173               results cached.
174
175       This method creates a new class method on the calling package, called
176       "closest_to".
177
178   closest_to
179          $color = $pkg->closest_to( $orig, $space )
180
181       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
185       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

AUTHOR

189       Paul Evans <leonerd@leonerd.org.uk>
190
191
192
193perl v5.34.1                      2022-05-10                 Convert::Color(3)
Impressum