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

INITIALIZATION

907       This documents the Imager initialization function, which you will
908       almost never need to call.
909
910       init()
911           This is a function, not a method.
912
913           This function is a mess, it can take the following named
914           parameters:
915
916           •   "log" - name of a log file to log Imager's actions to.  Not all
917               actions are logged, but the debugging memory allocator does log
918               allocations here.  Ignored if Imager has been built without
919               logging support.  Preferably use the open_log() method instead.
920
921           •   "loglevel" - the maximum level of message to log.  Default: 1.
922
923           •   "warn_obsolete" - if this is non-zero then Imager will warn
924               when you attempt to use obsoleted parameters or functionality.
925               This currently only includes the old GIF output options instead
926               of tags.
927
928           •   "t1log" - if non-zero then T1lib will be configured to produce
929               a log file.  This will fail if there are any existing T1lib
930               font objects.
931
932           Example:
933
934             Imager::init(log => 'trace.log', loglevel => 9);
935

LOGGING METHODS

937       Imager can open an internal log to send debugging information to.  This
938       log is extensively used in Imager's tests, but you're unlikely to use
939       it otherwise.
940
941       If Imager has been built with logging disabled, the methods fail
942       quietly.
943
944       open_log()
945           Open the Imager debugging log file.
946
947           •   "log" - the file name to log to.  If this is undef logging
948               information is sent to the standard error stream.
949
950           •   "loglevel" the level of logging to produce.  Default: 1.
951
952           Returns a true value if the log file was opened successfully.
953
954             # send debug output to test.log
955             Imager->open_log(log => "test.log");
956
957             # send debug output to stderr
958             Imager->open_log();
959
960       close_log()
961           Close the Imager debugging log file and disable debug logging.
962
963           No parameters.
964
965             Imager->close_log();
966
967       log()
968            Imager->log($message)
969            Imager->log($message, $level)
970
971           This method does not use named parameters.
972
973           The default for $level is 1.
974
975           Send a message to the debug log.
976
977             Imager->log("My code got here!");
978
979       is_logging()
980           Returns a true value if logging is enabled.
981

AUTHOR

983       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
984

SEE ALSO

986       Imager(3), Imager::Files(3), Imager::Draw(3), Imager::Color(3),
987       Imager::Fill(3), Imager::Font(3), Imager::Transformations(3),
988       Imager::Engines(3), Imager::Filters(3), Imager::Expr(3),
989       Imager::Matrix2d(3), Imager::Fountain(3)
990
991
992
993perl v5.32.1                      2021-01-27             Imager::ImageTypes(3)
Impressum