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 Channel masks are deprecated.
403 setmask()
405 $mask = $img->getmask();
406 $img->setmask(mask=>8); # modify alpha only
407 ...
409 $img->setmask(mask=>$mask); # restore previous mask
411 "setmask()" is used to set the channel mask of the image. See
413 "getmask()" for details.
414 Channel masks are deprecated.
416 Palette Type Images
418 Paletted images keep an array of up to 256 colors, and each pixel is
419 stored as an index into that array.
420 In general you can work with paletted images in the same way as RGB
422 images, except that if you attempt to draw to a paletted image with a
423 color that is not in the image's palette, the image will be converted
424 to an RGB image. This means that drawing on a paletted image with
425 anti-aliasing enabled will almost certainly convert the image to RGB.
426 Palette management takes place through "addcolors()", "setcolors()",
428 "getcolors()" and "findcolor()":
429 addcolors()
431 You can add colors to a paletted image with the addcolors() method:
432 my @colors = ( Imager::Color->new(255, 0, 0),
434 Imager::Color->new(0, 255, 0) );
435 my $index = $img->addcolors(colors=>\@colors);
436 The return value is the index of the first color added, or undef if
438 adding the colors would overflow the palette.
439 The only parameter is "colors" which must be a reference to an
441 array of Imager::Color objects.
442 setcolors()
444 $img->setcolors(start=>$start, colors=>\@colors);
445 Once you have colors in the palette you can overwrite them with the
447 "setcolors()" method: "setcolors()" returns true on success.
448 Parameters:
450 • start - the first index to be set. Default: 0
452 • colors - reference to an array of Imager::Color objects.
454 getcolors()
456 To retrieve existing colors from the palette use the getcolors()
457 method:
458 # get the whole palette
460 my @colors = $img->getcolors();
461 # get a single color
462 my $color = $img->getcolors(start=>$index);
463 # get a range of colors
464 my @colors = $img->getcolors(start=>$index, count=>$count);
465 findcolor()
467 To quickly find a color in the palette use findcolor():
468 my $index = $img->findcolor(color=>$color);
470 which returns undef on failure, or the index of the color.
472 Parameter:
474 • color - an Imager::Color object.
476 colorcount()
478 Returns the number of colors in the image's palette:
479 my $count = $img->colorcount;
481 maxcolors()
483 Returns the maximum size of the image's palette.
484 my $maxcount = $img->maxcolors;
486 Color Distribution
488 getcolorcount()
489 Calculates the number of colors in an image.
490 The amount of memory used by this is proportional to the number of
492 colors present in the image, so to avoid using too much memory you
493 can supply a maxcolors() parameter to limit the memory used.
494 Note: getcolorcount() treats the image as an 8-bit per sample
496 image.
497 • "maxcolors" - the maximum number of colors to return. Default:
499 unlimited.
500 if (defined($img->getcolorcount(maxcolors=>512)) {
502 print "Less than 512 colors in image\n";
503 }
504 getcolorusagehash()
506 Calculates a histogram of colors used by the image.
507 • "maxcolors" - the maximum number of colors to return. Default:
509 unlimited.
510 Returns a reference to a hash where the keys are the raw color as
512 bytes, and the values are the counts for that color.
513 The alpha channel of the image is ignored. If the image is gray
515 scale then the hash keys will each be a single character.
516 my $colors = $img->getcolorusagehash;
518 my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
519 print "#0000FF used $blue_count times\n";
520 getcolorusage()
522 Calculates color usage counts and returns just the counts.
523 • "maxcolors" - the maximum number of colors to return. Default:
525 unlimited.
526 Returns a list of the color frequencies in ascending order.
528 my @counts = $img->getcolorusage;
530 print "The most common color is used $counts[0] times\n";
531 Conversion Between Image Types
533 Warning: if you draw on a paletted image with colors that aren't in the
534 palette, the image will be internally converted to a normal image.
535 to_paletted()
537 You can create a new paletted image from an existing image using
538 the to_paletted() method:
539 $palimg = $img->to_paletted(\%opts)
541 where %opts contains the options specified under "Quantization
543 options".
544 # convert to a paletted image using the web palette
546 # use the closest color to each pixel
547 my $webimg = $img->to_paletted({ make_colors => 'webmap' });
548 # convert to a paletted image using a fairly optimal palette
550 # use an error diffusion dither to try to reduce the average error
551 my $optimag = $img->to_paletted({ make_colors => 'mediancut',
552 translate => 'errdiff' });
553 to_rgb8()
555 You can convert a paletted image (or any image) to an 8-bit/channel
556 RGB image with:
557 $rgbimg = $img->to_rgb8;
559 No parameters.
561 to_rgb16()
563 Convert a paletted image (or any image) to a 16-bit/channel RGB
564 image.
565 $rgbimg = $img->to_rgb16;
567 No parameters.
569 to_rgb_double()
571 Convert a paletted image (or any image) to an double/channel direct
572 color image.
573 $rgbimg = $img->to_rgb_double;
575 No parameters.
577 masked()
579 Creates a masked image. A masked image lets you create an image
580 proxy object that protects parts of the underlying target image.
581 In the discussion below there are 3 image objects involved:
583 • the masked image - the return value of the masked() method.
585 Any writes to this image are written to the target image,
586 assuming the mask image allows it.
587 • the mask image - the image that protects writes to the target
589 image. Supplied as the "mask" parameter to the masked()
590 method.
591 • the target image - the image you called the masked() method on.
593 Any writes to the masked image end up on this image.
594 Parameters:
596 • mask - the mask image. If not supplied then all pixels in the
598 target image are writable. On each write to the masked image,
599 only pixels that have non-zero in channel 0 of the mask image
600 will be written to the original image. Default: none, if not
601 supplied then no masking is done, but the other parameters are
602 still honored.
603 • left, top - the offset of writes to the target image. eg. if
605 you attempt to set pixel (x,y) in the masked image, then pixel
606 (x+left, y+top) will be written to in the original image.
607 • bottom, right - the bottom right of the area in the target
609 available from the masked image.
610 Masked images let you control which pixels are modified in an
612 underlying image. Where the first channel is completely black in
613 the mask image, writes to the underlying image are ignored.
614 For example, given a base image called $img:
616 my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
618 channels=>1);
619 # ... draw something on the mask
620 my $maskedimg = $img->masked(mask=>$mask);
621 # now draw on $maskedimg and it will only draw on areas of $img
623 # where $mask is non-zero in channel 0.
624 You can specify the region of the underlying image that is masked
626 using the left, top, right and bottom options.
627 If you just want a subset of the image, without masking, just
629 specify the region without specifying a mask. For example:
630 # just work with a 100x100 region of $img
632 my $maskedimg = $img->masked(left => 100, top=>100,
633 right=>200, bottom=>200);
634 make_palette()
636 This doesn't perform an image conversion, but it can be used to
637 construct a common palette for use in several images:
638 my @colors = Imager->make_palette(\%opts, @images);
640 You must supply at least one image, even if the "make_colors"
642 parameter produces a fixed palette.
643 On failure returns no colors and you can check "Imager->errstr".
645 Tags
647 Image tags contain meta-data about the image, ie. information not
648 stored as pixels of the image.
649 At the perl level each tag has a name or code and a value, which is an
651 integer or an arbitrary string. An image can contain more than one tag
652 with the same name or code, but having more than one tag with the same
653 name is discouraged.
654 You can retrieve tags from an image using the tags() method, you can
656 get all of the tags in an image, as a list of array references, with
657 the code or name of the tag followed by the value of the tag.
658 Imager's support for fairly limited, for access to pretty much all
660 image metadata you may want to try Image::ExifTool.
661 tags()
663 Retrieve tags from the image.
664 With no parameters, retrieves a list array references, each
666 containing a name and value: all tags in the image:
667 # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
669 my @alltags = $img->tags;
670 print $_->[0], ":", $_->[1], "\n" for @all_tags;
671 # or put it in a hash, but this will lose duplicates
673 my %alltags = map @$_, $img->tags;
674 in scalar context this returns the number of tags:
676 my $num_tags = $img->tags;
678 or you can get all tags values for the given name:
680 my @namedtags = $img->tags(name => $name);
682 in scalar context this returns the first tag of that name:
684 my $firstnamed = $img->tags(name => $name);
686 or a given code:
688 my @tags = $img->tags(code=>$code);
690 addtag()
692 You can add tags using the addtag() method, either by name:
693 my $index = $img->addtag(name=>$name, value=>$value);
695 or by code:
697 my $index = $img->addtag(code=>$code, value=>$value);
699 Setting tags by "code" is deprecated. If you have a use for this
701 please open an issue.
702 deltag()
704 You can remove tags with the deltag() method, either by index:
705 $img->deltag(index=>$index);
707 or by name:
709 $img->deltag(name=>$name);
711 or by code:
713 $img->deltag(code=>$code);
715 In each case deltag() returns the number of tags deleted.
717 Setting or deleting tags by "code" is deprecated. If you have a
719 use for this please open an issue.
720 settag()
722 settag() replaces any existing tags with a new tag. This is
723 equivalent to calling deltag() then addtag().
724 Common Tags
726 Many tags are only meaningful for one format. GIF looping information
727 is pretty useless for JPEG for example. Thus, many tags are set by
728 only a single reader or used by a single writer. For a complete list
729 of format specific tags see Imager::Files.
730 Since tags are a relatively new addition their use is not wide spread
732 but eventually we hope to have all the readers for various formats set
733 some standard information.
734 • "i_xres", "i_yres" - The spatial resolution of the image in pixels
736 per inch. If the image format uses a different scale, eg. pixels
737 per meter, then this value is converted. A floating point number
738 stored as a string.
739 # our image was generated as a 300 dpi image
741 $img->settag(name => 'i_xres', value => 300);
742 $img->settag(name => 'i_yres', value => 300);
743 # 100 pixel/cm for a TIFF image
745 $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
746 # convert to pixels per inch, Imager will convert it back
747 $img->settag(name => 'i_xres', value => 100 * 2.54);
748 $img->settag(name => 'i_yres', value => 100 * 2.54);
749 • "i_aspect_only" - If this is non-zero then the values in i_xres and
751 i_yres are treated as a ratio only. If the image format does not
752 support aspect ratios then this is scaled so the smaller value is
753 72 DPI.
754 • "i_incomplete" - If this tag is present then the whole image could
756 not be read. This isn't implemented for all images yet, and may
757 not be.
758 • "i_lines_read" - If "i_incomplete" is set then this tag may be set
760 to the number of scan lines successfully read from the file. This
761 can be used to decide whether an image is worth processing.
762 • i_format - The file format this file was read from.
764 • i_background - used when writing an image with an alpha channel to
766 a file format that doesn't support alpha channels. The "write"
767 method will convert a normal color specification like "#FF0000"
768 into a color object for you, but if you set this as a tag you will
769 need to format it like "color("red","green","blue")", eg
770 color(255,0,0).
771 • "i_comment" - used when reading or writing several image formats.
773 If the format has only one text field it will be read into the
774 "i_comment" tag or written to the file.
775 Quantization options
777 These options can be specified when calling "to_paletted()" in
778 Imager::ImageTypes, write_multi() for GIF files, when writing a single
779 image with the "gifquant" option set to "gen", or for direct calls to
780 i_writegif_gen() and i_writegif_callback().
781 • "colors" - An arrayref of colors that are fixed. Note that some
783 color generators will ignore this. If this is supplied it will be
784 filled with the color table generated for the image.
785 • "transp" - The type of transparency processing to perform for
787 images with an alpha channel where the output format does not have
788 a proper alpha channel (eg. GIF). This can be any of:
789 • "none" - No transparency processing is done. (default)
791 • "threshold" - pixels more transparent than "tr_threshold" are
793 rendered as transparent.
794 • "errdiff" - An error diffusion dither is done on the alpha
796 channel. Note that this is independent of the translation
797 performed on the color channels, so some combinations may cause
798 undesired artifacts.
799 • "ordered" - the ordered dither specified by tr_orddith is
801 performed on the alpha channel.
802 This will only be used if the image has an alpha channel, and if
804 there is space in the palette for a transparency color.
805 • "tr_threshold" - the highest alpha value at which a pixel will be
807 made transparent when "transp" is 'threshold'. (0-255, default 127)
808 • "tr_errdiff" - The type of error diffusion to perform on the alpha
810 channel when "transp" is "errdiff". This can be any defined error
811 diffusion type except for custom (see "errdiff" below).
812 • "tr_orddith" - The type of ordered dither to perform on the alpha
814 channel when "transp" is 'ordered'. Possible values are:
815 • "random" - A semi-random map is used. The map is the same each
817 time.
818 • "dot8" - 8x8 dot dither.
820 • "dot4" - 4x4 dot dither
822 • "hline" - horizontal line dither.
824 • "vline" - vertical line dither.
826 • "/line", "slashline" - diagonal line dither
828 • "\line", "backline" - diagonal line dither
830 • "tiny" - dot matrix dither (currently the default). This is
832 probably the best for displays (like web pages).
833 • "custom" - A custom dither matrix is used - see "tr_map".
835 • "tr_map" - When tr_orddith is custom this defines an 8 x 8 matrix
837 of integers representing the transparency threshold for pixels
838 corresponding to each position. This should be a 64 element array
839 where the first 8 entries correspond to the first row of the
840 matrix. Values should be between 0 and 255.
841 • "make_colors" - Defines how the quantization engine will build the
843 palette(s). Currently this is ignored if "translate" is "giflib",
844 but that may change. Possible values are:
845 • "none" - only colors supplied in 'colors' are used.
847 • "webmap" - the web color map is used (need URL here.)
849 • "addi" - The original code for generating the color map (Addi's
851 code) is used.
852 • "mediancut" - Uses a median-cut algorithm, faster than "addi",
854 but not as good a result.
855 • "mono", "monochrome" - a fixed black and white palette,
857 suitable for producing bi-level images (eg. facsimile)
858 • "gray", "gray4", "gray16" - make fixed gray palette with 256, 4
860 or 16 entries respectively.
861 Other methods may be added in the future.
863 • "colors" - an arrayref containing Imager::Color objects, which
865 represents the starting set of colors to use in translating the
866 images. "webmap" will ignore this. On return the final colors
867 used are copied back into this array (which is expanded if
868 necessary.)
869 • "max_colors" - the maximum number of colors to use in the image.
871 • "translate" - The method used to translate the RGB values in the
873 source image into the colors selected by make_colors. Note that
874 make_colors is ignored when "translate" is "giflib".
875 Possible values are:
877 • "giflib" - this is a historical equivalent for "closest" that
879 also forces "make_colors" to "mediancut".
880 • "closest" - the closest color available is used.
882 • "perturb" - the pixel color is modified by "perturb", and the
884 closest color is chosen.
885 • "errdiff" - an error diffusion dither is performed. If the
887 supplied (or generated) palette contains only grays the source
888 colors are converted to gray before error diffusion is
889 performed.
890 It's possible other "translate" values will be added.
892 • "errdiff" - The type of error diffusion dither to perform. These
894 values (except for custom) can also be used in tr_errdif.
895 • "floyd" - Floyd-Steinberg dither
897 • "jarvis" - Jarvis, Judice and Ninke dither
899 • "stucki" - Stucki dither
901 • "custom" - custom. If you use this you must also set
903 "errdiff_width", "errdiff_height" and "errdiff_map".
904 • "errdiff_width", "errdiff_height", "errdiff_orig", "errdiff_map" -
906 When "translate" is "errdiff" and "errdiff" is "custom" these
907 define a custom error diffusion map. "errdiff_width" and
908 "errdiff_height" define the size of the map in the arrayref in
909 "errdiff_map". "errdiff_orig" is an integer which indicates the
910 current pixel position in the top row of the map.
911 • "perturb" - When translate is "perturb" this is the magnitude of
913 the random bias applied to each channel of the pixel before it is
914 looked up in the color table.
915
917 This documents the Imager initialization function, which you will
918 almost never need to call.
919 init()
921 This is a function, not a method.
922 This function is a mess, it can take the following named
924 parameters:
925 • "log" - name of a log file to log Imager's actions to. Not all
927 actions are logged, but the debugging memory allocator does log
928 allocations here. Ignored if Imager has been built without
929 logging support. Preferably use the open_log() method instead.
930 • "loglevel" - the maximum level of message to log. Default: 1.
932 • "warn_obsolete" - if this is non-zero then Imager will warn
934 when you attempt to use obsoleted parameters or functionality.
935 This currently only includes the old GIF output options instead
936 of tags.
937 • "t1log" - if non-zero then T1lib will be configured to produce
939 a log file. This will fail if there are any existing T1lib
940 font objects.
941 Example:
943 Imager::init(log => 'trace.log', loglevel => 9);
945
947 Imager can open an internal log to send debugging information to. This
948 log is extensively used in Imager's tests, but you're unlikely to use
949 it otherwise.
950 If Imager has been built with logging disabled, the methods fail
952 quietly.
953 open_log()
955 Open the Imager debugging log file.
956 • "log" - the file name to log to. If this is undef logging
958 information is sent to the standard error stream.
959 • "loglevel" the level of logging to produce. Default: 1.
961 Returns a true value if the log file was opened successfully.
963 # send debug output to test.log
965 Imager->open_log(log => "test.log");
966 # send debug output to stderr
968 Imager->open_log();
969 close_log()
971 Close the Imager debugging log file and disable debug logging.
972 No parameters.
974 Imager->close_log();
976 log()
978 Imager->log($message)
979 Imager->log($message, $level)
980 This method does not use named parameters.
982 The default for $level is 1.
984 Send a message to the debug log.
986 Imager->log("My code got here!");
988 is_logging()
990 Returns a true value if logging is enabled.
991
993 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
994
996 Imager(3), Imager::Files(3), Imager::Draw(3), Imager::Color(3),
997 Imager::Fill(3), Imager::Font(3), Imager::Transformations(3),
998 Imager::Engines(3), Imager::Filters(3), Imager::Expr(3),
999 Imager::Matrix2d(3), Imager::Fountain(3)
1000perl v5.36.0 2022-07-22 Imager::ImageTypes(3)