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   $color = Convert::Color->new( STRING )
56       Return a new value to represent the color specified by the string. This
57       string should be prefixed by the name of the color space to which it
58       applies. For example
59
60        rgb:RED,GREEN,BLUE
61        rgb8:RRGGBB
62        rgb16:RRRRGGGGBBBB
63        hsv:HUE,SAT,VAL
64        hsl:HUE,SAT,LUM
65        cmy:CYAN,MAGENTA,YELLOW
66        cmyk:CYAN,MAGENTA,YELLOW,KEY
67
68        vga:NAME
69        vga:INDEX
70
71        x11:NAME
72
73       For more detail, see the constructor of the color space subclass in
74       question.
75

METHODS

77   ( $red, $green, $blue ) = $color->rgb
78       Returns the individual red, green and blue color components of the
79       color value. For RGB values, this is done directly. For values in other
80       spaces, this is done by first converting them to an RGB value using
81       their "to_rgb()" method.
82

COLOR SPACE CONVERSIONS

84       Cross-conversion between color spaces is provided by the "convert_to()"
85       method, assisted by helper methods in the two color space classes
86       involved.
87
88       When converting $color from color space SRC to color space DEST, the
89       following operations are attemped, in this order. SRC and DEST refer to
90       the names of the color spaces, e.g. "rgb".
91
92       1.  If SRC and DEST are equal, return $color as it stands.
93
94       2.  If the SRC space's class provides a "convert_to_DEST" method, use
95           it.
96
97       3.  If the DEST space's class provides a "new_from_SRC" constructor,
98           call it and pass $color.
99
100       4.  If the DEST space's class provides a "new_rgb" constructor, convert
101           $color to red/green/blue components then call it.
102
103       5.  If none of these operations worked, then throw an exception.
104
105       These functions may be called in the following ways:
106
107        $other = $color->convert_to_DEST()
108        $other = Dest::Class->new_from_SRC( $color )
109        $other = Dest::Class->new_rgb( $color->rgb )
110
111   $other = $color->convert_to( $space )
112       Attempt to convert the color into its representation in the given
113       space. See above for the various ways this may be achieved.
114
115       If the relevant subclass has already been loaded (either explicitly, or
116       implicitly by either the "new" or "convert_to" methods), then a
117       specific conversion method will be installed in the class.
118
119        $other = $color->as_$space
120
121       Methods of this form are currently "AUTOLOAD"ed if they do not yet
122       exist, but this feature should not be relied upon - see below.
123

AUTOLOADED CONVERSION METHODS

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

OTHER METHODS

139       As well as the above, it is likely the subclass will provide accessors
140       to directly obtain the components of its representation in the specific
141       space.  For more detail, see the documentation for the specific
142       subclass in question.
143

SUBCLASS METHODS

145       This base class is intended to be subclassed to provide more color
146       spaces.
147
148   $class->register_color_space( $space )
149       A subclass should call this method to register itself as a named color
150       space.
151
152   $class->register_palette( %args )
153       A subclass that provides a fixed set of color values should call this
154       method, to set up automatic conversions that look for the closest match
155       within the set. This conversion process is controlled by the %args:
156
157       enumerate => STRING or CODE
158               A method name or anonymous CODE reference which will be used to
159               generate the list of color values.
160
161       enumerate_once => STRING or CODE
162               As per "enumerate", but will be called only once and the
163               results cached.
164
165       This method creates a new class method on the calling package, called
166       "closest_to".
167
168       $color = $pkg->closest_to( $orig, $space )
169
170       Returns the color in the space closest to the given value. The distance
171       is measured in the named space; defaulting to "rgb" if this is not
172       provided.
173
174       In the case of a tie, where two or more colors have the same distance
175       from the target, the first one will be chosen.
176

AUTHOR

178       Paul Evans <leonerd@leonerd.org.uk>
179
180
181
182perl v5.32.1                      2021-01-27                 Convert::Color(3)
Impressum