1Imager::ImageTypes(3) User Contributed Perl DocumentationImager::ImageTypes(3)
2
6 Imager::ImageTypes - image models for Imager
7
9 use Imager;
10 $img = Imager->new(); # Empty image (size is 0 by 0)
12 $img->open(file=>'lena.png',type=>'png'); # Read image from file
13 $img = Imager->new(xsize=>400, ysize=>300); # RGB data
15 $img = Imager->new(xsize=>400, ysize=>300, # Grayscale
17 channels=>1); #
18 $img = Imager->new(xsize=>400, ysize=>300, # RGB with alpha
20 channels=>4); #
21 $img = Imager->new(xsize=>200, ysize=>200,
23 type=>'paletted'); # paletted image
24 $img = Imager->new(xsize=>200, ysize=>200,
26 bits=>16); # 16 bits/channel rgb
27 $img = Imager->new(xsize=>200, ysize=>200,
29 bits=>'double'); # 'double' floating point
30 # per channel
31 $img->img_set(xsize=>500, ysize=>500, # reset the image object
33 channels=>4);
34 # Example getting information about an Imager object
37 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 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 } 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 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
80 Imager supports two basic models of image:
81 · 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 · paletted - an index into a table of colors is stored for each
86 pixel.
87 Direct color or paletted images can have 1 to 4 samples per color
89 stored. Imager treats these as follows:
90 · 1 sample per color - gray scale image.
92 · 2 samples per color - gray scale image with alpha channel, allowing
94 transparency.
95 · 3 samples per color - RGB image.
97 · 4 samples per color - RGB image with alpha channel, allowing
99 transparency.
100 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 Paletted images are always 8-bits/sample.
106 To query an existing image about it's parameters see the "bits()",
108 "type()", "getwidth()", "getheight()", "getchannels()" and "virtual()"
109 methods.
110 The coordinate system in Imager has the origin in the upper left
112 corner, see Imager::Draw for details.
113 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 Creating Imager Objects
119 new()
120 $img = Imager->new();
121 $img->read(file=>"alligator.ppm") or die $img->errstr;
122 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 %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 You can also read a file from new():
132 $img = Imager->new(file => "someimage.png");
134 The parameters for new are:
136 · "xsize", "ysize" - Defines the width and height in pixels of
138 the image. These must be positive.
139 If not supplied then only placeholder object is created, which
141 can be supplied to the "read()" or "img_set()" methods.
142 · "channels" - The number of channels for the image. Default 3.
144 Valid values are from 1 to 4.
145 · "model" - this overrides the value, if any, supplied for
147 "channels". This can be one of "gray", "graya", "rgb" or
148 "rgba".
149 · "bits" - The storage type for samples in the image. Default:
151 8. Valid values are:
152 · 8 - One byte per sample. 256 discrete values.
154 · 16 - 16-bits per sample, 65536 discrete values.
156 · "double" - one C double per sample.
158 Note: you can use any Imager function on any sample size image.
160 Paletted images always use 8 bits/sample.
162 · "type" - either 'direct' or 'paletted'. Default: 'direct'.
164 Direct images store color values for each pixel.
166 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 In most cases when working with Imager you will want to use the
171 "direct" image type.
172 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 · "maxcolors" - the maximum number of colors in a paletted image.
178 Default: 256. This must be in the range 1 through 256.
179 · "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 my $im = Imager->new(file => $filename);
186 · "filetype" - treated as the file format parameter, as for
188 "type" with the read() method, eg:
189 my $im = Imager->new(file => $filename, filetype => "gif");
191 In most cases Imager will detect the file's format itself.
193 In the simplest case just supply the width and height of the image:
195 # 8 bit/sample, RGB image
197 my $img = Imager->new(xsize => $width, ysize => $height);
198 or if you want an alpha channel:
200 # 8 bits/sample, RGBA image
202 my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
203 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 To create paletted images, set the 'type' parameter to 'paletted':
209 $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
211 which creates an image with a maximum of 256 colors, which you can
213 change by supplying the "maxcolors" parameter.
214 For improved color precision you can use the bits parameter to
216 specify 16 bit per channel:
217 $img = Imager->new(xsize=>200, ysize=>200,
219 channels=>3, bits=>16);
220 or for even more precision:
222 $img = Imager->new(xsize=>200, ysize=>200,
224 channels=>3, bits=>'double');
225 to get an image that uses a double for each channel.
227 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 If you want an empty Imager object to call the read() method on,
233 just call new() with no parameters:
234 my $img = Imager->new;
236 $img->read(file=>$filename)
237 or die $img->errstr;
238 Though it's much easier now to just call new() with a "file"
240 parameter:
241 my $img = Imager->new(file => $filename)
243 or die Imager->errstr;
244 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 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 $img->img_set(xsize=>500, ysize=>500, channels=>4);
256 This takes exactly the same parameters as the new() method,
258 excluding those for reading from files.
259 Image Attribute functions
261 These return basic attributes of an image object.
262 getwidth()
264 print "Image width: ", $img->getwidth(), "\n";
265 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 getheight()
273 print "Image height: ", $img->getheight(), "\n";
274 Same details apply as for "getwidth()".
276 getchannels()
278 print "Image has ",$img->getchannels(), " channels\n";
279 Returns the number of channels in an image.
281 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 Returns an empty list if the image object is not initialized.
287 colorchannels()
289 Returns the number of color channels.
290 Currently this is always 1 or 3, but may be 0 for some rare images
292 in a future version of Imager.
293 Returns an empty list if the image object is not initialized.
295 colormodel()
297 Returns the color model of the image, including whether there is an
298 alpha channel.
299 By default this is returned as a string, one of "unknown", "gray",
301 "graya", "rgb" or "rgba".
302 If you call "colormodel()" with a true numeric parameter:
304 my $model = $img->colormodel(numeric => 1);
306 then the color model is returned as a number, mapped as follows:
308 Numeric String
310 ------- ------
311 0 unknown
312 1 gray
313 2 graya
314 3 rgb
315 4 rgba
316 alphachannel()
318 Returns the channel index of the alpha channel of the image.
319 This is 1 for grayscale images with alpha, 3 for RGB images with
321 alpha and will return "undef" for all other images.
322 Returns an empty list if the image object is not initialized.
324 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 if ($img->bits eq 8) {
331 # fast but limited to 8-bits/sample
332 }
333 else {
334 # slower but more precise
335 }
336 Returns an empty list if the image object is not initialized.
338 type()
340 The type() method returns either 'direct' for direct color images
341 or 'paletted' for paletted images.
342 if ($img->type eq 'paletted') {
344 # print the palette
345 for my $color ($img->getcolors) {
346 print join(",", $color->rgba), "\n";
347 }
348 }
349 Returns an empty list if the image object is not initialized.
351 virtual()
353 The virtual() method returns non-zero if the image contains no
354 actual pixels, for example masked images.
355 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 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 In scalar context, returns true if the image is bi-level.
364 In list context returns a list:
366 ($is_bilevel, $zero_is_white) = $img->is_bilevel;
368 An image is considered bi-level, if all of the following are true:
370 · the image is a paletted image
372 · the image has 1 or 3 channels
374 · the image has only 2 colors in the palette
376 · those 2 colors are black and white, in either order.
378 If a real bi-level organization image is ever added to Imager, this
380 function will return true for that too.
381 Returns an empty list if the image object is not initialized.
383 Direct Type Images
385 Direct images store the color value directly for each pixel in the
386 image.
387 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 "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 setmask()
403 $mask = $img->getmask();
404 $img->setmask(mask=>8); # modify alpha only
405 ...
407 $img->setmask(mask=>$mask); # restore previous mask
409 "setmask()" is used to set the channel mask of the image. See
411 "getmask()" for details.
412 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 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 Palette management takes place through "addcolors()", "setcolors()",
424 "getcolors()" and "findcolor()":
425 addcolors()
427 You can add colors to a paletted image with the addcolors() method:
428 my @colors = ( Imager::Color->new(255, 0, 0),
430 Imager::Color->new(0, 255, 0) );
431 my $index = $img->addcolors(colors=>\@colors);
432 The return value is the index of the first color added, or undef if
434 adding the colors would overflow the palette.
435 The only parameter is "colors" which must be a reference to an
437 array of Imager::Color objects.
438 setcolors()
440 $img->setcolors(start=>$start, colors=>\@colors);
441 Once you have colors in the palette you can overwrite them with the
443 "setcolors()" method: "setcolors()" returns true on success.
444 Parameters:
446 · start - the first index to be set. Default: 0
448 · colors - reference to an array of Imager::Color objects.
450 getcolors()
452 To retrieve existing colors from the palette use the getcolors()
453 method:
454 # 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 findcolor()
463 To quickly find a color in the palette use findcolor():
464 my $index = $img->findcolor(color=>$color);
466 which returns undef on failure, or the index of the color.
468 Parameter:
470 · color - an Imager::Color object.
472 colorcount()
474 Returns the number of colors in the image's palette:
475 my $count = $img->colorcount;
477 maxcolors()
479 Returns the maximum size of the image's palette.
480 my $maxcount = $img->maxcolors;
482 Color Distribution
484 getcolorcount()
485 Calculates the number of colors in an image.
486 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 Note: getcolorcount() treats the image as an 8-bit per sample
492 image.
493 · "maxcolors" - the maximum number of colors to return. Default:
495 unlimited.
496 if (defined($img->getcolorcount(maxcolors=>512)) {
498 print "Less than 512 colors in image\n";
499 }
500 getcolorusagehash()
502 Calculates a histogram of colors used by the image.
503 · "maxcolors" - the maximum number of colors to return. Default:
505 unlimited.
506 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 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 my $colors = $img->getcolorusagehash;
514 my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
515 print "#0000FF used $blue_count times\n";
516 getcolorusage()
518 Calculates color usage counts and returns just the counts.
519 · "maxcolors" - the maximum number of colors to return. Default:
521 unlimited.
522 Returns a list of the color frequencies in ascending order.
524 my @counts = $img->getcolorusage;
526 print "The most common color is used $counts[0] times\n";
527 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 to_paletted()
533 You can create a new paletted image from an existing image using
534 the to_paletted() method:
535 $palimg = $img->to_paletted(\%opts)
537 where %opts contains the options specified under "Quantization
539 options".
540 # 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 # 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 to_rgb8()
551 You can convert a paletted image (or any image) to an 8-bit/channel
552 RGB image with:
553 $rgbimg = $img->to_rgb8;
555 No parameters.
557 to_rgb16()
559 Convert a paletted image (or any image) to a 16-bit/channel RGB
560 image.
561 $rgbimg = $img->to_rgb16;
563 No parameters.
565 to_rgb_double()
567 Convert a paletted image (or any image) to an double/channel direct
568 color image.
569 $rgbimg = $img->to_rgb_double;
571 No parameters.
573 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 In the discussion below there are 3 image objects involved:
579 · 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 · the mask image - the image that protects writes to the target
585 image. Supplied as the "mask" parameter to the masked()
586 method.
587 · the target image - the image you called the masked() method on.
589 Any writes to the masked image end up on this image.
590 Parameters:
592 · 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 · 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 · bottom, right - the bottom right of the area in the target
605 available from the masked image.
606 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 For example, given a base image called $img:
612 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 # now draw on $maskedimg and it will only draw on areas of $img
619 # where $mask is non-zero in channel 0.
620 You can specify the region of the underlying image that is masked
622 using the left, top, right and bottom options.
623 If you just want a subset of the image, without masking, just
625 specify the region without specifying a mask. For example:
626 # just work with a 100x100 region of $img
628 my $maskedimg = $img->masked(left => 100, top=>100,
629 right=>200, bottom=>200);
630 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 my @colors = Imager->make_palette(\%opts, @images);
636 You must supply at least one image, even if the "make_colors"
638 parameter produces a fixed palette.
639 On failure returns no colors and you can check "Imager->errstr".
641 Tags
643 Image tags contain meta-data about the image, ie. information not
644 stored as pixels of the image.
645 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 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 Imager's support for fairly limited, for access to pretty much all
656 image metadata you may want to try Image::ExifTool.
657 tags()
659 Retrieve tags from the image.
660 With no parameters, retrieves a list array references, each
662 containing a name and value: all tags in the image:
663 # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
665 my @alltags = $img->tags;
666 print $_->[0], ":", $_->[1], "\n" for @all_tags;
667 # or put it in a hash, but this will lose duplicates
669 my %alltags = map @$_, $img->tags;
670 in scalar context this returns the number of tags:
672 my $num_tags = $img->tags;
674 or you can get all tags values for the given name:
676 my @namedtags = $img->tags(name => $name);
678 in scalar context this returns the first tag of that name:
680 my $firstnamed = $img->tags(name => $name);
682 or a given code:
684 my @tags = $img->tags(code=>$code);
686 addtag()
688 You can add tags using the addtag() method, either by name:
689 my $index = $img->addtag(name=>$name, value=>$value);
691 or by code:
693 my $index = $img->addtag(code=>$code, value=>$value);
695 deltag()
697 You can remove tags with the deltag() method, either by index:
698 $img->deltag(index=>$index);
700 or by name:
702 $img->deltag(name=>$name);
704 or by code:
706 $img->deltag(code=>$code);
708 In each case deltag() returns the number of tags deleted.
710 settag()
712 settag() replaces any existing tags with a new tag. This is
713 equivalent to calling deltag() then addtag().
714 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 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 · "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 # 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 # 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 · "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 · "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 · "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 · i_format - The file format this file was read from.
754 · 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 · "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 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 · "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 · "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 · "none" - No transparency processing is done. (default)
781 · "threshold" - pixels more transparent than "tr_threshold" are
783 rendered as transparent.
784 · "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 · "ordered" - the ordered dither specified by tr_orddith is
791 performed on the alpha channel.
792 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 · "tr_threshold" - the highest alpha value at which a pixel will be
797 made transparent when "transp" is 'threshold'. (0-255, default 127)
798 · "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 · "tr_orddith" - The type of ordered dither to perform on the alpha
804 channel when "transp" is 'ordered'. Possible values are:
805 · "random" - A semi-random map is used. The map is the same each
807 time.
808 · "dot8" - 8x8 dot dither.
810 · "dot4" - 4x4 dot dither
812 · "hline" - horizontal line dither.
814 · "vline" - vertical line dither.
816 · "/line", "slashline" - diagonal line dither
818 · "\line", "backline" - diagonal line dither
820 · "tiny" - dot matrix dither (currently the default). This is
822 probably the best for displays (like web pages).
823 · "custom" - A custom dither matrix is used - see "tr_map".
825 · "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 · "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 · "none" - only colors supplied in 'colors' are used.
837 · "webmap" - the web color map is used (need URL here.)
839 · "addi" - The original code for generating the color map (Addi's
841 code) is used.
842 · "mediancut" - Uses a median-cut algorithm, faster than "addi",
844 but not as good a result.
845 · "mono", "monochrome" - a fixed black and white palette,
847 suitable for producing bi-level images (eg. facsimile)
848 · "gray", "gray4", "gray16" - make fixed gray palette with 256, 4
850 or 16 entries respectively.
851 Other methods may be added in the future.
853 · "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 · "max_colors" - the maximum number of colors to use in the image.
861 · "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 Possible values are:
867 · "giflib" - this is a historical equivalent for "closest" that
869 also forces "make_colors" to "mediancut".
870 · "closest" - the closest color available is used.
872 · "perturb" - the pixel color is modified by "perturb", and the
874 closest color is chosen.
875 · "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 It's possible other "translate" values will be added.
882 · "errdiff" - The type of error diffusion dither to perform. These
884 values (except for custom) can also be used in tr_errdif.
885 · "floyd" - Floyd-Steinberg dither
887 · "jarvis" - Jarvis, Judice and Ninke dither
889 · "stucki" - Stucki dither
891 · "custom" - custom. If you use this you must also set
893 "errdiff_width", "errdiff_height" and "errdiff_map".
894 · "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 · "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
907 This documents the Imager initialization function, which you will
908 almost never need to call.
909 init()
911 This is a function, not a method.
912 This function is a mess, it can take the following named
914 parameters:
915 · "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 · "loglevel" - the maximum level of message to log. Default: 1.
922 · "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 · "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 Example:
933 Imager::init(log => 'trace.log', loglevel => 9);
935
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 If Imager has been built with logging disabled, the methods fail
942 quietly.
943 open_log()
945 Open the Imager debugging log file.
946 · "log" - the file name to log to. If this is undef logging
948 information is sent to the standard error stream.
949 · "loglevel" the level of logging to produce. Default: 1.
951 Returns a true value if the log file was opened successfully.
953 # send debug output to test.log
955 Imager->open_log(log => "test.log");
956 # send debug output to stderr
958 Imager->open_log();
959 close_log()
961 Close the Imager debugging log file and disable debug logging.
962 No parameters.
964 Imager->close_log();
966 log()
968 Imager->log($message)
969 Imager->log($message, $level)
970 This method does not use named parameters.
972 The default for $level is 1.
974 Send a message to the debug log.
976 Imager->log("My code got here!");
978 is_logging()
980 Returns a true value if logging is enabled.
981
983 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
984
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)
990perl v5.32.0 2020-07-28 Imager::ImageTypes(3)