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 $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 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 vga:NAME
69 vga:INDEX
70 x11:NAME
72 For more detail, see the constructor of the color space subclass in
74 question.
75
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
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 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 1. If SRC and DEST are equal, return $color as it stands.
93 2. If the SRC space's class provides a "convert_to_DEST" method, use
95 it.
96 3. If the DEST space's class provides a "new_from_SRC" constructor,
98 call it and pass $color.
99 4. If the DEST space's class provides a "new_rgb" constructor, convert
101 $color to red/green/blue components then call it.
102 5. If none of these operations worked, then throw an exception.
104 These functions may be called in the following ways:
106 $other = $color->convert_to_DEST()
108 $other = Dest::Class->new_from_SRC( $color )
109 $other = Dest::Class->new_rgb( $color->rgb )
110 $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 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 $other = $color->as_$space
120 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
125 This class provides "AUTOLOAD" and "can" behaviour which automatically
126 constructs conversion methods. The following method calls are
127 identical:
128 $color->convert_to('rgb')
130 $color->as_rgb
131 The generated method will be stored in the package, so that future
133 calls will not have the AUTOLOAD overhead.
134 This feature is deprecated and should not be relied upon, due to the
136 delicate nature of "AUTOLOAD".
137
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
145 This base class is intended to be subclassed to provide more color
146 spaces.
147 $class->register_color_space( $space )
149 A subclass should call this method to register itself as a named color
150 space.
151 $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 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 enumerate_once => STRING or CODE
162 As per "enumerate", but will be called only once and the
163 results cached.
164 This method creates a new class method on the calling package, called
166 "closest_to".
167 $color = $pkg->closest_to( $orig, $space )
169 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 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
178 Paul Evans <leonerd@leonerd.org.uk>
179perl v5.32.1 2021-01-27 Convert::Color(3)