Imager::ImageTypes(3pm)

1Imager::ImageTypes(3) User Contributed Perl DocumentationImager::ImageTypes(3)
2
3
4

NAME

6       Imager::ImageTypes - image models for Imager
7

SYNOPSIS

9         use Imager;
10
11         $img = Imager->new(); #  Empty image (size is 0 by 0)
12         $img->open(file=>'lena.png',type=>'png'); # Read image from file
13
14         $img = Imager->new(xsize=>400, ysize=>300); # RGB data
15
16         $img = Imager->new(xsize=>400, ysize=>300,  # Grayscale
17                            channels=>1);            #
18
19         $img = Imager->new(xsize=>400, ysize=>300,  # RGB with alpha
20                            channels=>4);            #
21
22         $img = Imager->new(xsize=>200, ysize=>200,
23                            type=>'paletted');       # paletted image
24
25         $img = Imager->new(xsize=>200, ysize=>200,
26                            bits=>16);               # 16 bits/channel rgb
27
28         $img = Imager->new(xsize=>200, ysize=>200,
29                            bits=>'double');         # 'double' floating point
30                                                     #  per channel
31
32         $img->img_set(xsize=>500, ysize=>500,       # reset the image object
33                       channels=>4);
34
35
36         # Example getting information about an Imager object
37
38         print "Image information:\n";
39         print "Width:        ", $img->getwidth(),    "\n";
40         print "Height:       ", $img->getheight(),   "\n";
41         print "Channels:     ", $img->getchannels(), "\n";
42         print "Bits/Channel: ", $img->bits(),        "\n";
43         print "Virtual:      ", $img->virtual() ? "Yes" : "No", "\n";
44         my $colorcount = $img->getcolorcount(maxcolors=>512);
45               print "Actual number of colors in image: ";
46         print defined($colorcount) ? $colorcount : ">512", "\n";
47         print "Type:         ", $img->type(),        "\n";
48
49         if ($img->type() eq 'direct') {
50           print "Modifiable Channels: ";
51           print join " ", map {
52             ($img->getmask() & 1<<$_) ? $_ : ()
53           } 0..$img->getchannels();
54           print "\n";
55
56         } else {
57           # palette info
58           my $count = $img->colorcount;
59           @colors = $img->getcolors();
60           print "Palette size: $count\n";
61           my $mx = @colors > 4 ? 4 : 0+@colors;
62           print "First $mx entries:\n";
63           for (@colors[0..$mx-1]) {
64             my @res = $_->rgba();
65             print "(", join(", ", @res[0..$img->getchannels()-1]), ")\n";
66           }
67         }
68
69         my @tags = $img->tags();
70         if (@tags) {
71           print "Tags:\n";
72           for(@tags) {
73             print shift @$_, ": ", join " ", @$_, "\n";
74           }
75         } else {
76           print "No tags in image\n";
77         }
78

DESCRIPTION

80       Imager supports two basic models of image:
81
82       ·   direct color - all samples are stored for every pixel.  eg. for an
83           8-bit/sample RGB image, 24 bits are stored for each pixel.
84
85       ·   paletted - an index into a table of colors is stored for each
86           pixel.
87
88       Direct color or paletted images can have 1 to 4 samples per color
89       stored.  Imager treats these as follows:
90
91       ·   1 sample per color - gray scale image.
92
93       ·   2 samples per color - gray scale image with alpha channel, allowing
94           transparency.
95
96       ·   3 samples per color - RGB image.
97
98       ·   4 samples per color - RGB image with alpha channel, allowing
99           transparency.
100
101       Direct color images can have sample sizes of 8-bits per sample, 16-bits
102       per sample or a double precision floating point number per sample
103       (64-bits on many systems).
104
105       Paletted images are always 8-bits/sample.
106
107       To query an existing image about it's parameters see the "bits()",
108       "type()", "getwidth()", "getheight()", "getchannels()" and "virtual()"
109       methods.
110
111       The coordinate system in Imager has the origin in the upper left
112       corner, see Imager::Draw for details.
113
114       The alpha channel when one is present is considered unassociated - ie
115       the color data has not been scaled by the alpha channel.  Note that not
116       all code follows this (recent) rule, but will over time.
117
118   Creating Imager Objects
119       new()
120             $img = Imager->new();
121             $img->read(file=>"alligator.ppm") or die $img->errstr;
122
123           Here "new()" creates an empty image with width and height of zero.
124           It's only useful for creating an Imager object to call the read()
125           method on later.
126
127             %opts = (xsize=>300, ysize=>200);
128             $img = Imager->new(%opts); # create direct mode RGBA image
129             $img = Imager->new(%opts, channels=>4); # create direct mode RGBA image
130
131           You can also read a file from new():
132
133             $img = Imager->new(file => "someimage.png");
134
135           The parameters for new are:
136
137           ·   "xsize", "ysize" - Defines the width and height in pixels of
138               the image.  These must be positive.
139
140               If not supplied then only placeholder object is created, which
141               can be supplied to the "read()" or "img_set()" methods.
142
143           ·   "channels" - The number of channels for the image.  Default 3.
144               Valid values are from 1 to 4.
145
146           ·   "bits" - The storage type for samples in the image.  Default:
147               8.  Valid values are:
148
149               ·   8 - One byte per sample.  256 discrete values.
150
151               ·   16 - 16-bits per sample, 65536 discrete values.
152
153               ·   "double" - one C double per sample.
154
155               Note: you can use any Imager function on any sample size image.
156
157               Paletted images always use 8 bits/sample.
158
159           ·   "type" - either 'direct' or 'paletted'.  Default: 'direct'.
160
161               Direct images store color values for each pixel.
162
163               Paletted images keep a table of up to 256 colors called the
164               palette, each pixel is represented as an index into that table.
165
166               In most cases when working with Imager you will want to use the
167               "direct" image type.
168
169               If you draw on a "paletted" image with a color not in the
170               image's palette then Imager will transparently convert it to a
171               "direct" image.
172
173           ·   "maxcolors" - the maximum number of colors in a paletted image.
174               Default: 256.  This must be in the range 1 through 256.
175
176           ·   "file", "fh", "fd", "callback", "readcb" - specify a file name,
177               filehandle, file descriptor or callback to read image data
178               from.  See Imager::Files for details.  The typical use is:
179
180                 my $im = Imager->new(file => $filename);
181
182           ·   "filetype" - treated as the file format parameter, as for
183               "type" with the read() method, eg:
184
185                 my $im = Imager->new(file => $filename, filetype => "gif");
186
187               In most cases Imager will detect the file's format itself.
188
189           In the simplest case just supply the width and height of the image:
190
191             # 8 bit/sample, RGB image
192             my $img = Imager->new(xsize => $width, ysize => $height);
193
194           or if you want an alpha channel:
195
196             # 8 bits/sample, RGBA image
197             my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
198
199           Note that it is possible for image creation to fail, for example if
200           channels is out of range, or if the image would take too much
201           memory.
202
203           To create paletted images, set the 'type' parameter to 'paletted':
204
205             $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
206
207           which creates an image with a maximum of 256 colors, which you can
208           change by supplying the "maxcolors" parameter.
209
210           For improved color precision you can use the bits parameter to
211           specify 16 bit per channel:
212
213             $img = Imager->new(xsize=>200, ysize=>200,
214                                channels=>3, bits=>16);
215
216           or for even more precision:
217
218             $img = Imager->new(xsize=>200, ysize=>200,
219                                channels=>3, bits=>'double');
220
221           to get an image that uses a double for each channel.
222
223           Note that as of this writing all functions should work on images
224           with more than 8-bits/channel, but many will only work at only
225           8-bit/channel precision.
226
227           If you want an empty Imager object to call the read() method on,
228           just call new() with no parameters:
229
230             my $img = Imager->new;
231             $img->read(file=>$filename)
232               or die $img->errstr;
233
234           Though it's much easier now to just call new() with a "file"
235           parameter:
236
237             my $img = Imager->new(file => $filename)
238               or die Imager->errstr;
239
240       img_set()
241           img_set destroys the image data in the object and creates a new one
242           with the given dimensions and channels.  For a way to convert image
243           data between formats see the "convert()" method.
244
245             $img->img_set(xsize=>500, ysize=>500, channels=>4);
246
247           This takes exactly the same parameters as the new() method.
248
249   Image Attribute functions
250       These return basic attributes of an image object.
251
252       getwidth()
253             print "Image width: ", $img->getwidth(), "\n";
254
255           The "getwidth()" method returns the width of the image.  This value
256           comes either from "new()" with "xsize", "ysize" parameters or from
257           reading data from a file with "read()".  If called on an image that
258           has no valid data in it like "Imager->new()" returns, the return
259           value of "getwidth()" is undef.
260
261       getheight()
262             print "Image height: ", $img->getheight(), "\n";
263
264           Same details apply as for "getwidth()".
265
266       getchannels()
267             print "Image has ",$img->getchannels(), " channels\n";
268
269           To get the number of channels in an image "getchannels()" is used.
270
271       bits()
272           The bits() method retrieves the number of bits used to represent
273           each channel in a pixel, 8 for a normal image, 16 for 16-bit image
274           and 'double' for a double/channel image.
275
276             if ($img->bits eq 8) {
277               # fast but limited to 8-bits/sample
278             }
279             else {
280               # slower but more precise
281             }
282
283       type()
284           The type() method returns either 'direct' for direct color images
285           or 'paletted' for paletted images.
286
287             if ($img->type eq 'paletted') {
288               # print the palette
289               for my $color ($img->getcolors) {
290                 print join(",", $color->rgba), "\n";
291               }
292             }
293
294       virtual()
295           The virtual() method returns non-zero if the image contains no
296           actual pixels, for example masked images.
297
298           This may also be used for non-native Imager images in the future,
299           for example, for an Imager object that draws on an SDL surface.
300
301       is_bilevel()
302           Tests if the image will be written as a monochrome or bi-level
303           image for formats that support that image organization.
304
305           In scalar context, returns true if the image is bi-level.
306
307           In list context returns a list:
308
309             ($is_bilevel, $zero_is_white) = $img->is_bilevel;
310
311           An image is considered bi-level, if all of the following are true:
312
313           ·   the image is a paletted image
314
315           ·   the image has 1 or 3 channels
316
317           ·   the image has only 2 colors in the palette
318
319           ·   those 2 colors are black and white, in either order.
320
321           If a real bi-level organization image is ever added to Imager, this
322           function will return true for that too.
323
324   Direct Type Images
325       Direct images store the color value directly for each pixel in the
326       image.
327
328       getmask()
329             @rgbanames = qw( red green blue alpha );
330             my $mask = $img->getmask();
331             print "Modifiable channels:\n";
332             for (0..$img->getchannels()-1) {
333               print $rgbanames[$_],"\n" if $mask & 1<<$_;
334             }
335
336           "getmask()" is used to fetch the current channel mask.  The mask
337           determines what channels are currently modifiable in the image.
338           The channel mask is an integer value, if the "i-th" least
339           significant bit is set the "i-th" channel is modifiable.  eg. a
340           channel mask of 0x5 means only channels 0 and 2 are writable.
341
342       setmask()
343             $mask = $img->getmask();
344             $img->setmask(mask=>8);     # modify alpha only
345
346               ...
347
348             $img->setmask(mask=>$mask); # restore previous mask
349
350           "setmask()" is used to set the channel mask of the image.  See
351           "getmask()" for details.
352
353   Palette Type Images
354       Paletted images keep an array of up to 256 colors, and each pixel is
355       stored as an index into that array.
356
357       In general you can work with paletted images in the same way as RGB
358       images, except that if you attempt to draw to a paletted image with a
359       color that is not in the image's palette, the image will be converted
360       to an RGB image.  This means that drawing on a paletted image with
361       anti-aliasing enabled will almost certainly convert the image to RGB.
362
363       Palette management takes place through "addcolors()", "setcolors()",
364       "getcolors()" and "findcolor()":
365
366       addcolors()
367           You can add colors to a paletted image with the addcolors() method:
368
369              my @colors = ( Imager::Color->new(255, 0, 0),
370                             Imager::Color->new(0, 255, 0) );
371              my $index = $img->addcolors(colors=>\@colors);
372
373           The return value is the index of the first color added, or undef if
374           adding the colors would overflow the palette.
375
376           The only parameter is "colors" which must be a reference to an
377           array of Imager::Color objects.
378
379       setcolors()
380             $img->setcolors(start=>$start, colors=>\@colors);
381
382           Once you have colors in the palette you can overwrite them with the
383           "setcolors()" method:  "setcolors()" returns true on success.
384
385           Parameters:
386
387           ·   start - the first index to be set.  Default: 0
388
389           ·   colors - reference to an array of Imager::Color objects.
390
391       getcolors()
392           To retrieve existing colors from the palette use the getcolors()
393           method:
394
395             # get the whole palette
396             my @colors = $img->getcolors();
397             # get a single color
398             my $color = $img->getcolors(start=>$index);
399             # get a range of colors
400             my @colors = $img->getcolors(start=>$index, count=>$count);
401
402       findcolor()
403           To quickly find a color in the palette use findcolor():
404
405             my $index = $img->findcolor(color=>$color);
406
407           which returns undef on failure, or the index of the color.
408
409           Parameter:
410
411           ·   color - an Imager::Color object.
412
413       colorcount()
414           Returns the number of colors in the image's palette:
415
416             my $count = $img->colorcount;
417
418       maxcolors()
419           Returns the maximum size of the image's palette.
420
421             my $maxcount = $img->maxcolors;
422
423   Color Distribution
424       getcolorcount()
425           Calculates the number of colors in an image.
426
427           The amount of memory used by this is proportional to the number of
428           colors present in the image, so to avoid using too much memory you
429           can supply a maxcolors() parameter to limit the memory used.
430
431           Note: getcolorcount() treats the image as an 8-bit per sample
432           image.
433
434           ·   "maxcolors" - the maximum number of colors to return.  Default:
435               unlimited.
436
437             if (defined($img->getcolorcount(maxcolors=>512)) {
438               print "Less than 512 colors in image\n";
439             }
440
441       getcolorusagehash()
442           Calculates a histogram of colors used by the image.
443
444           ·   "maxcolors" - the maximum number of colors to return.  Default:
445               unlimited.
446
447           Returns a reference to a hash where the keys are the raw color as
448           bytes, and the values are the counts for that color.
449
450           The alpha channel of the image is ignored.  If the image is gray
451           scale then the hash keys will each be a single character.
452
453             my $colors = $img->getcolorusagehash;
454             my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
455             print "#0000FF used $blue_count times\n";
456
457       getcolorusage()
458           Calculates color usage counts and returns just the counts.
459
460           ·   "maxcolors" - the maximum number of colors to return.  Default:
461               unlimited.
462
463           Returns a list of the color frequencies in ascending order.
464
465             my @counts = $img->getcolorusage;
466             print "The most common color is used $counts[0] times\n";
467
468   Conversion Between Image Types
469       Warning: if you draw on a paletted image with colors that aren't in the
470       palette, the image will be internally converted to a normal image.
471
472       to_paletted()
473           You can create a new paletted image from an existing image using
474           the to_paletted() method:
475
476            $palimg = $img->to_paletted(\%opts)
477
478           where %opts contains the options specified under "Quantization
479           options".
480
481             # convert to a paletted image using the web palette
482             # use the closest color to each pixel
483             my $webimg = $img->to_paletted({ make_colors => 'webmap' });
484
485             # convert to a paletted image using a fairly optimal palette
486             # use an error diffusion dither to try to reduce the average error
487             my $optimag = $img->to_paletted({ make_colors => 'mediancut',
488                                               translate => 'errdiff' });
489
490       to_rgb8()
491           You can convert a paletted image (or any image) to an 8-bit/channel
492           RGB image with:
493
494             $rgbimg = $img->to_rgb8;
495
496           No parameters.
497
498       to_rgb16()
499           Convert a paletted image (or any image) to a 16-bit/channel RGB
500           image.
501
502             $rgbimg = $img->to_rgb16;
503
504           No parameters.
505
506       to_rgb_double()
507           Convert a paletted image (or any image) to an double/channel direct
508           color image.
509
510             $rgbimg = $img->to_rgb_double;
511
512           No parameters.
513
514       masked()
515           Creates a masked image.  A masked image lets you create an image
516           proxy object that protects parts of the underlying target image.
517
518           In the discussion below there are 3 image objects involved:
519
520           ·   the masked image - the return value of the masked() method.
521               Any writes to this image are written to the target image,
522               assuming the mask image allows it.
523
524           ·   the mask image - the image that protects writes to the target
525               image.  Supplied as the "mask" parameter to the masked()
526               method.
527
528           ·   the target image - the image you called the masked() method on.
529               Any writes to the masked image end up on this image.
530
531           Parameters:
532
533           ·   mask - the mask image.  If not supplied then all pixels in the
534               target image are writable.  On each write to the masked image,
535               only pixels that have non-zero in channel 0 of the mask image
536               will be written to the original image.  Default: none, if not
537               supplied then no masking is done, but the other parameters are
538               still honored.
539
540           ·   left, top - the offset of writes to the target image.  eg. if
541               you attempt to set pixel (x,y) in the masked image, then pixel
542               (x+left, y+top) will be written to in the original image.
543
544           ·   bottom, right - the bottom right of the area in the target
545               available from the masked image.
546
547           Masked images let you control which pixels are modified in an
548           underlying image.  Where the first channel is completely black in
549           the mask image, writes to the underlying image are ignored.
550
551           For example, given a base image called $img:
552
553             my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
554                                    channels=>1);
555             # ... draw something on the mask
556             my $maskedimg = $img->masked(mask=>$mask);
557
558             # now draw on $maskedimg and it will only draw on areas of $img
559             # where $mask is non-zero in channel 0.
560
561           You can specify the region of the underlying image that is masked
562           using the left, top, right and bottom options.
563
564           If you just want a subset of the image, without masking, just
565           specify the region without specifying a mask.  For example:
566
567             # just work with a 100x100 region of $img
568             my $maskedimg = $img->masked(left => 100, top=>100,
569                                          right=>200, bottom=>200);
570
571   Tags
572       Image tags contain meta-data about the image, ie. information not
573       stored as pixels of the image.
574
575       At the perl level each tag has a name or code and a value, which is an
576       integer or an arbitrary string.  An image can contain more than one tag
577       with the same name or code, but having more than one tag with the same
578       name is discouraged.
579
580       You can retrieve tags from an image using the tags() method, you can
581       get all of the tags in an image, as a list of array references, with
582       the code or name of the tag followed by the value of the tag.
583
584       tags()
585           Retrieve tags from the image.
586
587           With no parameters, retrieves a list array references, each
588           containing a name and value: all tags in the image:
589
590             # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
591             my @alltags = $img->tags;
592             print $_->[0], ":", $_->[1], "\n" for @all_tags;
593
594             # or put it in a hash, but this will lose duplicates
595             my %alltags = map @$_, $img->tags;
596
597           in scalar context this returns the number of tags:
598
599             my $num_tags = $img->tags;
600
601           or you can get all tags values for the given name:
602
603             my @namedtags = $img->tags(name => $name);
604
605           in scalar context this returns the first tag of that name:
606
607             my $firstnamed = $img->tags(name => $name);
608
609           or a given code:
610
611             my @tags = $img->tags(code=>$code);
612
613       addtag()
614           You can add tags using the addtag() method, either by name:
615
616             my $index = $img->addtag(name=>$name, value=>$value);
617
618           or by code:
619
620             my $index = $img->addtag(code=>$code, value=>$value);
621
622       deltag()
623           You can remove tags with the deltag() method, either by index:
624
625             $img->deltag(index=>$index);
626
627           or by name:
628
629             $img->deltag(name=>$name);
630
631           or by code:
632
633             $img->deltag(code=>$code);
634
635           In each case deltag() returns the number of tags deleted.
636
637       settag()
638           settag() replaces any existing tags with a new tag.  This is
639           equivalent to calling deltag() then addtag().
640
641   Common Tags
642       Many tags are only meaningful for one format.  GIF looping information
643       is pretty useless for JPEG for example.  Thus, many tags are set by
644       only a single reader or used by a single writer.  For a complete list
645       of format specific tags see Imager::Files.
646
647       Since tags are a relatively new addition their use is not wide spread
648       but eventually we hope to have all the readers for various formats set
649       some standard information.
650
651       ·   "i_xres", "i_yres" - The spatial resolution of the image in pixels
652           per inch.  If the image format uses a different scale, eg. pixels
653           per meter, then this value is converted.  A floating point number
654           stored as a string.
655
656             # our image was generated as a 300 dpi image
657             $img->settag(name => 'i_xres', value => 300);
658             $img->settag(name => 'i_yres', value => 300);
659
660             # 100 pixel/cm for a TIFF image
661             $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
662             # convert to pixels per inch, Imager will convert it back
663             $img->settag(name => 'i_xres', value => 100 * 2.54);
664             $img->settag(name => 'i_yres', value => 100 * 2.54);
665
666       ·   "i_aspect_only" - If this is non-zero then the values in i_xres and
667           i_yres are treated as a ratio only.  If the image format does not
668           support aspect ratios then this is scaled so the smaller value is
669           72 DPI.
670
671       ·   "i_incomplete" - If this tag is present then the whole image could
672           not be read.  This isn't implemented for all images yet, and may
673           not be.
674
675       ·   "i_lines_read" - If "i_incomplete" is set then this tag may be set
676           to the number of scan lines successfully read from the file.  This
677           can be used to decide whether an image is worth processing.
678
679       ·   i_format - The file format this file was read from.
680
681       ·   i_background - used when writing an image with an alpha channel to
682           a file format that doesn't support alpha channels.  The "write"
683           method will convert a normal color specification like "#FF0000"
684           into a color object for you, but if you set this as a tag you will
685           need to format it like "color("red","green","blue")", eg
686           color(255,0,0).
687
688   Quantization options
689       These options can be specified when calling "to_paletted()" in
690       Imager::ImageTypes, write_multi() for GIF files, when writing a single
691       image with the "gifquant" option set to "gen", or for direct calls to
692       i_writegif_gen() and i_writegif_callback().
693
694       ·   "colors" - An arrayref of colors that are fixed.  Note that some
695           color generators will ignore this.  If this is supplied it will be
696           filled with the color table generated for the image.
697
698       ·   "transp" - The type of transparency processing to perform for
699           images with an alpha channel where the output format does not have
700           a proper alpha channel (eg. GIF).  This can be any of:
701
702           ·   "none" - No transparency processing is done. (default)
703
704           ·   "threshold" - pixels more transparent than "tr_threshold" are
705               rendered as transparent.
706
707           ·   "errdiff" - An error diffusion dither is done on the alpha
708               channel.  Note that this is independent of the translation
709               performed on the color channels, so some combinations may cause
710               undesired artifacts.
711
712           ·   "ordered" - the ordered dither specified by tr_orddith is
713               performed on the alpha channel.
714
715           This will only be used if the image has an alpha channel, and if
716           there is space in the palette for a transparency color.
717
718       ·   "tr_threshold" - the highest alpha value at which a pixel will be
719           made transparent when "transp" is 'threshold'. (0-255, default 127)
720
721       ·   "tr_errdiff" - The type of error diffusion to perform on the alpha
722           channel when "transp" is "errdiff".  This can be any defined error
723           diffusion type except for custom (see "errdiff" below).
724
725       ·   "tr_orddith" - The type of ordered dither to perform on the alpha
726           channel when "transp" is 'ordered'.  Possible values are:
727
728           ·   "random" - A semi-random map is used.  The map is the same each
729               time.
730
731           ·   "dot8" - 8x8 dot dither.
732
733           ·   "dot4" - 4x4 dot dither
734
735           ·   "hline" - horizontal line dither.
736
737           ·   "vline" - vertical line dither.
738
739           ·   "/line", "slashline" - diagonal line dither
740
741           ·   "\line", "backline" - diagonal line dither
742
743           ·   "tiny" - dot matrix dither (currently the default).  This is
744               probably the best for displays (like web pages).
745
746           ·   "custom" - A custom dither matrix is used - see "tr_map".
747
748       ·   "tr_map" - When tr_orddith is custom this defines an 8 x 8 matrix
749           of integers representing the transparency threshold for pixels
750           corresponding to each position.  This should be a 64 element array
751           where the first 8 entries correspond to the first row of the
752           matrix.  Values should be between 0 and 255.
753
754       ·   "make_colors" - Defines how the quantization engine will build the
755           palette(s).  Currently this is ignored if "translate" is "giflib",
756           but that may change.  Possible values are:
757
758           ·   "none" - only colors supplied in 'colors' are used.
759
760           ·   "webmap" - the web color map is used (need URL here.)
761
762           ·   "addi" - The original code for generating the color map (Addi's
763               code) is used.
764
765           ·   "mediancut" - Uses a median-cut algorithm, faster than "addi",
766               but not as good a result.
767
768           ·   "mono", "monochrome" - a fixed black and white palette,
769               suitable for producing bi-level images (eg. facsimile)
770
771           Other methods may be added in the future.
772
773       ·   "colors" - an arrayref containing Imager::Color objects, which
774           represents the starting set of colors to use in translating the
775           images.  "webmap" will ignore this.  On return the final colors
776           used are copied back into this array (which is expanded if
777           necessary.)
778
779       ·   "max_colors" - the maximum number of colors to use in the image.
780
781       ·   "translate" - The method used to translate the RGB values in the
782           source image into the colors selected by make_colors.  Note that
783           make_colors is ignored when "translate" is "giflib".
784
785           Possible values are:
786
787           ·   "giflib" - this is a historical equivalent for "closest" that
788               also forces "make_colors" to "mediancut".
789
790           ·   "closest" - the closest color available is used.
791
792           ·   "perturb" - the pixel color is modified by "perturb", and the
793               closest color is chosen.
794
795           ·   "errdiff" - an error diffusion dither is performed.  If the
796               supplied (or generated) palette contains only grays the source
797               colors are converted to gray before error diffusion is
798               performed.
799
800           It's possible other "translate" values will be added.
801
802       ·   "errdiff" - The type of error diffusion dither to perform.  These
803           values (except for custom) can also be used in tr_errdif.
804
805           ·   "floyd" - Floyd-Steinberg dither
806
807           ·   "jarvis" - Jarvis, Judice and Ninke dither
808
809           ·   "stucki" - Stucki dither
810
811           ·   "custom" - custom.  If you use this you must also set
812               "errdiff_width", "errdiff_height" and "errdiff_map".
813
814       ·   "errdiff_width", "errdiff_height", "errdiff_orig", "errdiff_map" -
815           When "translate" is "errdiff" and "errdiff" is "custom" these
816           define a custom error diffusion map.  "errdiff_width" and
817           "errdiff_height" define the size of the map in the arrayref in
818           "errdiff_map".  "errdiff_orig" is an integer which indicates the
819           current pixel position in the top row of the map.
820
821       ·   "perturb" - When translate is "perturb" this is the magnitude of
822           the random bias applied to each channel of the pixel before it is
823           looked up in the color table.
824

INITIALIZATION

826       This documents the Imager initialization function, which you will
827       almost never need to call.
828
829       init()
830           This is a function, not a method.
831
832           This function is a mess, it can take the following named
833           parameters:
834
835           ·   "log" - name of a log file to log Imager's actions to.  Not all
836               actions are logged, but the debugging memory allocator does log
837               allocations here.  Ignored if Imager has been built without
838               logging support.  Preferably use the open_log() method instead.
839
840           ·   "loglevel" - the maximum level of message to log.  Default: 1.
841
842           ·   "warn_obsolete" - if this is non-zero then Imager will warn
843               when you attempt to use obsoleted parameters or functionality.
844               This currently only includes the old GIF output options instead
845               of tags.
846
847           ·   "t1log" - if non-zero then T1lib will be configured to produce
848               a log file.  This will fail if there are any existing T1lib
849               font objects.
850
851           Example:
852
853             Imager::init(log => 'trace.log', loglevel => 9);
854

LOGGING METHODS

856       Imager can open an internal log to send debugging information to.  This
857       log is extensively used in Imager's tests, but you're unlikely to use
858       it otherwise.
859
860       If Imager has been built with logging disabled, the methods fail
861       quietly.
862
863       open_log()
864           Open the Imager debugging log file.
865
866           ·   "log" - the file name to log to.  If this is undef logging
867               information is sent to the standard error stream.
868
869           ·   "loglevel" the level of logging to produce.  Default: 1.
870
871           Returns a true value if the log file was opened successfully.
872
873             # send debug output to test.log
874             Imager->open_log(log => "test.log");
875
876             # send debug output to stderr
877             Imager->open_log();
878
879       close_log()
880           Close the Imager debugging log file and disable debug logging.
881
882           No parameters.
883
884             Imager->close_log();
885
886       log()
887            Imager->log($message)
888            Imager->log($message, $level)
889
890           This method does not use named parameters.
891
892           The default for $level is 1.
893
894           Send a message to the debug log.
895
896             Imager->log("My code got here!");
897
898       is_logging()
899           Returns a true value if logging is enabled.
900

REVISION

902       $Revision$
903

AUTHORS

905       Tony Cook, Arnar M. Hrafnkelsson
906