Imager::Color(3pm)

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

NAME

6       Imager::Color - Color handling for Imager.
7

SYNOPSIS

9         use Imager;
10
11         $color = Imager::Color->new($red, $green, $blue);
12         $color = Imager::Color->new($red, $green, $blue, $alpha);
13         $color = Imager::Color->new("#C0C0FF"); # html color specification
14
15         $color->set($red, $green, $blue);
16         $color->set($red, $green, $blue, $alpha);
17         $color->set("#C0C0FF"); # html color specification
18
19         ($red, $green, $blue, $alpha) = $color->rgba();
20         @hsv = $color->hsv();
21
22         $color->info();
23
24         if ($color->equals(other=>$other_color)) {
25           ...
26         }
27

DESCRIPTION

29       This module handles creating color objects used by Imager.  The idea is
30       that in the future this module will be able to handle color space
31       calculations as well.
32
33       An Imager color consists of up to four components, each in the range 0
34       to 255. Unfortunately the meaning of the components can change
35       depending on the type of image you're dealing with:
36
37       ·   for 3 or 4 channel images the color components are red, green,
38           blue, alpha.
39
40       ·   for 1 or 2 channel images the color components are gray, alpha,
41           with the other two components ignored.
42
43       An alpha value of zero is fully transparent, an alpha value of 255 is
44       fully opaque.
45

METHODS

47       new This creates a color object to pass to functions that need a color
48           argument.
49
50       set This changes an already defined color.  Note that this does not
51           affect any places where the color has been used previously.
52
53       rgba()
54           This returns the red, green, blue and alpha channels of the color
55           the object contains.
56
57       info
58           Calling info merely dumps the relevant color to the log.
59
60       equals(other=>$other_color)
61       equals(other=>$other_color, ignore_alpha=>1)
62           Compares $self and color $other_color returning true if the color
63           components are the same.
64
65           Compares all four channels unless "ignore_alpha" is set.  If
66           "ignore_alpha" is set only the first three channels are compared.
67
68       You can specify colors in several different ways, you can just supply
69       simple values:
70
71       ·   simple numeric parameters - if you supply 3 or 4 numeric arguments,
72           you get a color made up of those RGB (and possibly A) components.
73
74       ·   a six hex digit web color, either "RRGGBB" or "#RRGGBB"
75
76       ·   an eight hex digit web color, either "RRGGBBAA" or "#RRGGBBAA".
77
78       ·   a 3 hex digit web color, "#RGB" - a value of F becomes 255.
79
80       ·   a color name, from whichever of the gimp "Named_Colors" file or X
81           "rgb.txt" is found first.  The same as using the "name" keyword.
82
83       You can supply named parameters:
84
85       ·   'red', 'green' and 'blue', optionally shortened to 'r', 'g' and
86           'b'.  The color components in the range 0 to 255.
87
88            # all of the following are equivalent
89            my $c1 = Imager::Color->new(red=>100, blue=>255, green=>0);
90            my $c2 = Imager::Color->new(r=>100, b=>255, g=>0);
91            my $c3 = Imager::Color->new(r=>100, blue=>255, g=>0);
92
93       ·   "hue", "saturation" and "value", optionally shortened to "h", "s"
94           and "v", to specify a HSV color.  0 <= hue < 360, 0 <= s <= 1 and 0
95           <= v <= 1.
96
97             # the same as RGB(127,255,127)
98             my $c1 = Imager::Color->new(hue=>120, v=>1, s=>0.5);
99             my $c1 = Imager::Color->new(hue=>120, value=>1, saturation=>0.5);
100
101       ·   "web", which can specify a 6 or 3 hex digit web color, in any of
102           the forms "#RRGGBB", "#RGB", "RRGGBB" or "RGB".
103
104             my $c1 = Imager::Color->new(web=>'#FFC0C0'); # pale red
105
106       ·   "gray" or "grey" which specifies a single channel, from 0 to 255.
107
108             # exactly the same
109             my $c1 = Imager::Color->new(gray=>128);
110             my $c1 = Imager::Color->new(grey=>128);
111
112       ·   "rgb" which takes a 3 member arrayref, containing each of the red,
113           green and blue values.
114
115             # the same
116             my $c1 = Imager::Color->new(rgb=>[255, 100, 0]);
117             my $c1 = Imager::Color->new(r=>255, g=>100, b=>0);
118
119       ·   "hsv" which takes a 3 member arrayref, containing each of hue,
120           saturation and value.
121
122             # the same
123             my $c1 = Imager::Color->new(hsv=>[120, 0.5, 1]);
124             my $c1 = Imager::Color->new(hue=>120, v=>1, s=>0.5);
125
126       ·   "gimp" which specifies a color from a GIMP palette file.  You can
127           specify the file name of the palette file with the 'palette'
128           parameter, or let Imager::Color look in various places, typically
129           "$HOME/gimp-1.x/palettes/Named_Colors" with and without the version
130           number, and in "/usr/share/gimp/palettes/".  The palette file must
131           have color names.
132
133             my $c1 = Imager::Color->new(gimp=>'snow');
134             my $c1 = Imager::Color->new(gimp=>'snow', palette=>'testimg/test_gimp_pal);
135
136       ·   "xname" which specifies a color from an X11 "rgb.txt" file.  You
137           can specify the file name of the "rgb.txt" file with the "palette"
138           parameter, or let Imager::Color look in various places, typically
139           "/usr/lib/X11/rgb.txt".
140
141             my $c1 = Imager::Color->new(xname=>'blue') # usually RGB(0, 0, 255)
142
143       ·   "builtin" which specifies a color from the built-in color table in
144           Imager::Color::Table.  The colors in this module are the same as
145           the default X11 "rgb.txt" file.
146
147             my $c1 = Imager::Color->new(builtin=>'black') # always RGB(0, 0, 0)
148
149       ·   "name" which specifies a name from either a GIMP palette, an X
150           "rgb.txt" file or the built-in color table, whichever is found
151           first.
152
153       ·   'channel0', 'channel1', etc, each of which specifies a single
154           channel.  These can be abbreviated to 'c0', 'c1' etc.
155
156       ·   'channels' which takes an arrayref of the channel values.
157
158       Optionally you can add an alpha channel to a color with the 'alpha' or
159       'a' parameter.
160
161       These color specifications can be used for both constructing new colors
162       with the new() method and modifying existing colors with the set()
163       method.
164

METHODS

166       hsv()
167               my($h, $s, $v, $alpha) = $color->hsv();
168
169           Returns the color as a Hue/Saturation/Value/Alpha tuple.
170
171       red
172       green
173       blue
174       alpha
175           Returns the respective component as an integer from 0 to 255.
176

AUTHOR

178       Arnar M. Hrafnkelsson, addi@umich.edu And a great deal of help from
179       others - see the "README" for a complete list.
180

NAME

SYNOPSIS

DESCRIPTION

METHODS

METHODS

AUTHOR

SEE ALSO