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() methods.
109 The coordinate system in Imager has the origin in the upper left
111 corner, see Imager::Draw for details.
112 The alpha channel when one is present is considered unassociated - ie
114 the color data has not been scaled by the alpha channel. Note that not
115 all code follows this (recent) rule, but will over time.
116 Creating Imager Objects
118 new()
119 $img = Imager->new();
120 $img->read(file=>"alligator.ppm") or die $img->errstr;
121 Here new() creates an empty image with width and height of zero.
123 It's only useful for creating an Imager object to call the read()
124 method on later.
125 %opts = (xsize=>300, ysize=>200);
127 $img = Imager->new(%opts); # create direct mode RGBA image
128 $img = Imager->new(%opts, channels=>4); # create direct mode RGBA image
129 You can also read a file from new():
131 $img = Imager->new(file => "someimage.png");
133 The parameters for new are:
135 • "xsize", "ysize" - Defines the width and height in pixels of
137 the image. These must be positive.
138 If not supplied then only placeholder object is created, which
140 can be supplied to the read() or img_set() methods.
141 • "channels" - The number of channels for the image. Default 3.
143 Valid values are from 1 to 4.
144 • "model" - this overrides the value, if any, supplied for
146 "channels". This can be one of "gray", "graya", "rgb" or
147 "rgba".
148 • "bits" - The storage type for samples in the image. Default:
150 8. Valid values are:
151 • 8 - One byte per sample. 256 discrete values.
153 • 16 - 16-bits per sample, 65536 discrete values.
155 • "double" - one C double per sample.
157 Note: you can use any Imager function on any sample size image.
159 Paletted images always use 8 bits/sample.
161 • "type" - either 'direct' or 'paletted'. Default: 'direct'.
163 Direct images store color values for each pixel.
165 Paletted images keep a table of up to 256 colors called the
167 palette, each pixel is represented as an index into that table.
168 In most cases when working with Imager you will want to use the
170 "direct" image type.
171 If you draw on a "paletted" image with a color not in the
173 image's palette then Imager will transparently convert it to a
174 "direct" image.
175 • "maxcolors" - the maximum number of colors in a paletted image.
177 Default: 256. This must be in the range 1 through 256.
178 • "file", "fh", "fd", "callback", "readcb", or "io" - specify a
180 file name, filehandle, file descriptor or callback to read
181 image data from. See Imager::Files for details. The typical
182 use is:
183 my $im = Imager->new(file => $filename);
185 • "filetype" - treated as the file format parameter, as for
187 "type" with the read() method, eg:
188 my $im = Imager->new(file => $filename, filetype => "gif");
190 In most cases Imager will detect the file's format itself.
192 In the simplest case just supply the width and height of the image:
194 # 8 bit/sample, RGB image
196 my $img = Imager->new(xsize => $width, ysize => $height);
197 or if you want an alpha channel:
199 # 8 bits/sample, RGBA image
201 my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
202 Note that it is possible for image creation to fail, for example if
204 channels is out of range, or if the image would take too much
205 memory.
206 To create paletted images, set the 'type' parameter to 'paletted':
208 $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
210 which creates an image with a maximum of 256 colors, which you can
212 change by supplying the "maxcolors" parameter.
213 For improved color precision you can use the bits parameter to
215 specify 16 bit per channel:
216 $img = Imager->new(xsize=>200, ysize=>200,
218 channels=>3, bits=>16);
219 or for even more precision:
221 $img = Imager->new(xsize=>200, ysize=>200,
223 channels=>3, bits=>'double');
224 to get an image that uses a double for each channel.
226 Note that as of this writing all functions should work on images
228 with more than 8-bits/channel, but many will only work at only
229 8-bit/channel precision.
230 If you want an empty Imager object to call the read() method on,
232 just call new() with no parameters:
233 my $img = Imager->new;
235 $img->read(file=>$filename)
236 or die $img->errstr;
237 Though it's much easier now to just call new() with a "file"
239 parameter:
240 my $img = Imager->new(file => $filename)
242 or die Imager->errstr;
243 If none of "xsize", "ysize", "file", "fh", "fd", "callback",
245 "readcb", "data", "io" is supplied, and other parameters are
246 supplied "Imager->new" will return failure rather than returning an
247 empty image object.
248 img_set()
250 img_set destroys the image data in the object and creates a new one
251 with the given dimensions and channels. For a way to convert image
252 data between formats see the convert() method.
253 $img->img_set(xsize=>500, ysize=>500, channels=>4);
255 This takes exactly the same parameters as the new() method,
257 excluding those for reading from files.
258 Image Attribute functions
260 These return basic attributes of an image object.
261 getwidth()
263 print "Image width: ", $img->getwidth(), "\n";
264 The getwidth() method returns the width of the image. This value
266 comes either from new() with "xsize", "ysize" parameters or from
267 reading data from a file with read(). If called on an image that
268 has no valid data in it like "Imager->new()" returns, the return
269 value of getwidth() is undef.
270 getheight()
272 print "Image height: ", $img->getheight(), "\n";
273 Same details apply as for "getwidth()".
275 getchannels()
277 print "Image has ",$img->getchannels(), " channels\n";
278 Returns the number of channels in an image.
280 Note: previously the number of channels in an image mapped directly
282 to the color model of the image, ie a 4 channel image was always
283 RGBA. This may change in a future release of Imager.
284 Returns an empty list if the image object is not initialized.
286 colorchannels()
288 Returns the number of color channels.
289 Currently this is always 1 or 3, but may be 0 for some rare images
291 in a future version of Imager.
292 Returns an empty list if the image object is not initialized.
294 colormodel()
296 Returns the color model of the image, including whether there is an
297 alpha channel.
298 By default this is returned as a string, one of "unknown", "gray",
300 "graya", "rgb" or "rgba".
301 If you call colormodel() with a true numeric parameter:
303 my $model = $img->colormodel(numeric => 1);
305 then the color model is returned as a number, mapped as follows:
307 Numeric String
309 ------- ------
310 0 unknown
311 1 gray
312 2 graya
313 3 rgb
314 4 rgba
315 alphachannel()
317 Returns the channel index of the alpha channel of the image.
318 This is 1 for grayscale images with alpha, 3 for RGB images with
320 alpha and will return "undef" for all other images.
321 Returns an empty list if the image object is not initialized.
323 bits()
325 The bits() method retrieves the number of bits used to represent
326 each channel in a pixel, 8 for a normal image, 16 for 16-bit image
327 and 'double' for a double/channel image.
328 if ($img->bits eq 8) {
330 # fast but limited to 8-bits/sample
331 }
332 else {
333 # slower but more precise
334 }
335 Returns an empty list if the image object is not initialized.
337 type()
339 The type() method returns either 'direct' for direct color images
340 or 'paletted' for paletted images.
341 if ($img->type eq 'paletted') {
343 # print the palette
344 for my $color ($img->getcolors) {
345 print join(",", $color->rgba), "\n";
346 }
347 }
348 Returns an empty list if the image object is not initialized.
350 virtual()
352 The virtual() method returns non-zero if the image contains no
353 actual pixels, for example masked images.
354 This may also be used for non-native Imager images in the future,
356 for example, for an Imager object that draws on an SDL surface.
357 is_bilevel()
359 Tests if the image will be written as a monochrome or bi-level
360 image for formats that support that image organization.
361 In scalar context, returns true if the image is bi-level.
363 In list context returns a list:
365 ($is_bilevel, $zero_is_white) = $img->is_bilevel;
367 An image is considered bi-level, if all of the following are true:
369 • the image is a paletted image
371 • the image has 1 or 3 channels
373 • the image has only 2 colors in the palette
375 • those 2 colors are black and white, in either order.
377 If a real bi-level organization image is ever added to Imager, this
379 function will return true for that too.
380 Returns an empty list if the image object is not initialized.
382 Direct Type Images
384 Direct images store the color value directly for each pixel in the
385 image.
386 getmask()
388 @rgbanames = qw( red green blue alpha );
389 my $mask = $img->getmask();
390 print "Modifiable channels:\n";
391 for (0..$img->getchannels()-1) {
392 print $rgbanames[$_],"\n" if $mask & 1<<$_;
393 }
394 getmask() is used to fetch the current channel mask. The mask
396 determines what channels are currently modifiable in the image.
397 The channel mask is an integer value, if the "i-th" least
398 significant bit is set the "i-th" channel is modifiable. eg. a
399 channel mask of 0x5 means only channels 0 and 2 are writable.
400 Channel masks are deprecated.
402 setmask()
404 $mask = $img->getmask();
405 $img->setmask(mask=>8); # modify alpha only
406 ...
408 $img->setmask(mask=>$mask); # restore previous mask
410 setmask() is used to set the channel mask of the image. See
412 "getmask()" for details.
413 Channel masks are deprecated.
415 Palette Type Images
417 Paletted images keep an array of up to 256 colors, and each pixel is
418 stored as an index into that array.
419 In general you can work with paletted images in the same way as RGB
421 images, except that if you attempt to draw to a paletted image with a
422 color that is not in the image's palette, the image will be converted
423 to an RGB image. This means that drawing on a paletted image with
424 anti-aliasing enabled will almost certainly convert the image to RGB.
425 Palette management takes place through addcolors(), setcolors(),
427 getcolors() and findcolor():
428 addcolors()
430 You can add colors to a paletted image with the addcolors() method:
431 my @colors = ( Imager::Color->new(255, 0, 0),
433 Imager::Color->new(0, 255, 0) );
434 my $index = $img->addcolors(colors=>\@colors);
435 The return value is the index of the first color added, or undef if
437 adding the colors would overflow the palette.
438 The only parameter is "colors" which must be a reference to an
440 array of Imager::Color objects.
441 setcolors()
443 $img->setcolors(start=>$start, colors=>\@colors);
444 Once you have colors in the palette you can overwrite them with the
446 setcolors() method: setcolors() returns true on success.
447 Parameters:
449 • start - the first index to be set. Default: 0
451 • colors - reference to an array of Imager::Color objects.
453 getcolors()
455 To retrieve existing colors from the palette use the getcolors()
456 method:
457 # get the whole palette
459 my @colors = $img->getcolors();
460 # get a single color
461 my $color = $img->getcolors(start=>$index);
462 # get a range of colors
463 my @colors = $img->getcolors(start=>$index, count=>$count);
464 findcolor()
466 To quickly find a color in the palette use findcolor():
467 my $index = $img->findcolor(color=>$color);
469 which returns undef on failure, or the index of the color.
471 Parameter:
473 • color - an Imager::Color object.
475 colorcount()
477 Returns the number of colors in the image's palette:
478 my $count = $img->colorcount;
480 maxcolors()
482 Returns the maximum size of the image's palette.
483 my $maxcount = $img->maxcolors;
485 Color Distribution
487 getcolorcount()
488 Calculates the number of colors in an image.
489 The amount of memory used by this is proportional to the number of
491 colors present in the image, so to avoid using too much memory you
492 can supply a maxcolors() parameter to limit the memory used.
493 Note: getcolorcount() treats the image as an 8-bit per sample
495 image.
496 • "maxcolors" - the maximum number of colors to return. Default:
498 unlimited.
499 if (defined($img->getcolorcount(maxcolors=>512)) {
501 print "Less than 512 colors in image\n";
502 }
503 getcolorusagehash()
505 Calculates a histogram of colors used by the image.
506 • "maxcolors" - the maximum number of colors to return. Default:
508 unlimited.
509 Returns a reference to a hash where the keys are the raw color as
511 bytes, and the values are the counts for that color.
512 The alpha channel of the image is ignored. If the image is gray
514 scale then the hash keys will each be a single character.
515 my $colors = $img->getcolorusagehash;
517 my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
518 print "#0000FF used $blue_count times\n";
519 getcolorusage()
521 Calculates color usage counts and returns just the counts.
522 • "maxcolors" - the maximum number of colors to return. Default:
524 unlimited.
525 Returns a list of the color frequencies in ascending order.
527 my @counts = $img->getcolorusage;
529 print "The most common color is used $counts[0] times\n";
530 Conversion Between Image Types
532 Warning: if you draw on a paletted image with colors that aren't in the
533 palette, the image will be internally converted to a normal image.
534 to_paletted()
536 You can create a new paletted image from an existing image using
537 the to_paletted() method:
538 $palimg = $img->to_paletted(\%opts)
540 where %opts contains the options specified under "Quantization
542 options".
543 # convert to a paletted image using the web palette
545 # use the closest color to each pixel
546 my $webimg = $img->to_paletted({ make_colors => 'webmap' });
547 # convert to a paletted image using a fairly optimal palette
549 # use an error diffusion dither to try to reduce the average error
550 my $optimag = $img->to_paletted({ make_colors => 'mediancut',
551 translate => 'errdiff' });
552 to_rgb8()
554 You can convert a paletted image (or any image) to an 8-bit/channel
555 RGB image with:
556 $rgbimg = $img->to_rgb8;
558 No parameters.
560 to_rgb16()
562 Convert a paletted image (or any image) to a 16-bit/channel RGB
563 image.
564 $rgbimg = $img->to_rgb16;
566 No parameters.
568 to_rgb_double()
570 Convert a paletted image (or any image) to an double/channel direct
571 color image.
572 $rgbimg = $img->to_rgb_double;
574 No parameters.
576 masked()
578 Creates a masked image. A masked image lets you create an image
579 proxy object that protects parts of the underlying target image.
580 In the discussion below there are 3 image objects involved:
582 • the masked image - the return value of the masked() method.
584 Any writes to this image are written to the target image,
585 assuming the mask image allows it.
586 • the mask image - the image that protects writes to the target
588 image. Supplied as the "mask" parameter to the masked()
589 method.
590 • the target image - the image you called the masked() method on.
592 Any writes to the masked image end up on this image.
593 Parameters:
595 • mask - the mask image. If not supplied then all pixels in the
597 target image are writable. On each write to the masked image,
598 only pixels that have non-zero in channel 0 of the mask image
599 will be written to the original image. Default: none, if not
600 supplied then no masking is done, but the other parameters are
601 still honored.
602 • left, top - the offset of writes to the target image. eg. if
604 you attempt to set pixel (x,y) in the masked image, then pixel
605 (x+left, y+top) will be written to in the original image.
606 • bottom, right - the bottom right of the area in the target
608 available from the masked image.
609 Masked images let you control which pixels are modified in an
611 underlying image. Where the first channel is completely black in
612 the mask image, writes to the underlying image are ignored.
613 For example, given a base image called $img:
615 my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
617 channels=>1);
618 # ... draw something on the mask
619 my $maskedimg = $img->masked(mask=>$mask);
620 # now draw on $maskedimg and it will only draw on areas of $img
622 # where $mask is non-zero in channel 0.
623 You can specify the region of the underlying image that is masked
625 using the left, top, right and bottom options.
626 If you just want a subset of the image, without masking, just
628 specify the region without specifying a mask. For example:
629 # just work with a 100x100 region of $img
631 my $maskedimg = $img->masked(left => 100, top=>100,
632 right=>200, bottom=>200);
633 make_palette()
635 This doesn't perform an image conversion, but it can be used to
636 construct a common palette for use in several images:
637 my @colors = Imager->make_palette(\%opts, @images);
639 You must supply at least one image, even if the "make_colors"
641 parameter produces a fixed palette.
642 On failure returns no colors and you can check "Imager->errstr".
644 Tags
646 Image tags contain meta-data about the image, ie. information not
647 stored as pixels of the image.
648 At the perl level each tag has a name or code and a value, which is an
650 integer or an arbitrary string. An image can contain more than one tag
651 with the same name or code, but having more than one tag with the same
652 name is discouraged.
653 You can retrieve tags from an image using the tags() method, you can
655 get all of the tags in an image, as a list of array references, with
656 the code or name of the tag followed by the value of the tag.
657 Imager's support for fairly limited, for access to pretty much all
659 image metadata you may want to try Image::ExifTool.
660 tags()
662 Retrieve tags from the image.
663 With no parameters, retrieves a list array references, each
665 containing a name and value: all tags in the image:
666 # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
668 my @alltags = $img->tags;
669 print $_->[0], ":", $_->[1], "\n" for @all_tags;
670 # or put it in a hash, but this will lose duplicates
672 my %alltags = map @$_, $img->tags;
673 in scalar context this returns the number of tags:
675 my $num_tags = $img->tags;
677 or you can get all tags values for the given name:
679 my @namedtags = $img->tags(name => $name);
681 in scalar context this returns the first tag of that name:
683 my $firstnamed = $img->tags(name => $name);
685 or a given code:
687 my @tags = $img->tags(code=>$code);
689 addtag()
691 You can add tags using the addtag() method, either by name:
692 my $index = $img->addtag(name=>$name, value=>$value);
694 or by code:
696 my $index = $img->addtag(code=>$code, value=>$value);
698 Setting tags by "code" is deprecated. If you have a use for this
700 please open an issue.
701 deltag()
703 You can remove tags with the deltag() method, either by index:
704 $img->deltag(index=>$index);
706 or by name:
708 $img->deltag(name=>$name);
710 or by code:
712 $img->deltag(code=>$code);
714 In each case deltag() returns the number of tags deleted.
716 Setting or deleting tags by "code" is deprecated. If you have a
718 use for this please open an issue.
719 settag()
721 settag() replaces any existing tags with a new tag. This is
722 equivalent to calling deltag() then addtag().
723 Common Tags
725 Many tags are only meaningful for one format. GIF looping information
726 is pretty useless for JPEG for example. Thus, many tags are set by
727 only a single reader or used by a single writer. For a complete list
728 of format specific tags see Imager::Files.
729 Since tags are a relatively new addition their use is not wide spread
731 but eventually we hope to have all the readers for various formats set
732 some standard information.
733 • "i_xres", "i_yres" - The spatial resolution of the image in pixels
735 per inch. If the image format uses a different scale, eg. pixels
736 per meter, then this value is converted. A floating point number
737 stored as a string.
738 # our image was generated as a 300 dpi image
740 $img->settag(name => 'i_xres', value => 300);
741 $img->settag(name => 'i_yres', value => 300);
742 # 100 pixel/cm for a TIFF image
744 $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
745 # convert to pixels per inch, Imager will convert it back
746 $img->settag(name => 'i_xres', value => 100 * 2.54);
747 $img->settag(name => 'i_yres', value => 100 * 2.54);
748 • "i_aspect_only" - If this is non-zero then the values in i_xres and
750 i_yres are treated as a ratio only. If the image format does not
751 support aspect ratios then this is scaled so the smaller value is
752 72 DPI.
753 • "i_incomplete" - If this tag is present then the whole image could
755 not be read. This isn't implemented for all images yet, and may
756 not be.
757 • "i_lines_read" - If "i_incomplete" is set then this tag may be set
759 to the number of scan lines successfully read from the file. This
760 can be used to decide whether an image is worth processing.
761 • i_format - The file format this file was read from.
763 • i_background - used when writing an image with an alpha channel to
765 a file format that doesn't support alpha channels. The "write"
766 method will convert a normal color specification like "#FF0000"
767 into a color object for you, but if you set this as a tag you will
768 need to format it like "color("red","green","blue")", eg
769 color(255,0,0).
770 • "i_comment" - used when reading or writing several image formats.
772 If the format has only one text field it will be read into the
773 "i_comment" tag or written to the file.
774 Quantization options
776 These options can be specified when calling "to_paletted()" in
777 Imager::ImageTypes, write_multi() for GIF files, when writing a single
778 image with the "gifquant" option set to "gen", or for direct calls to
779 i_writegif_gen() and i_writegif_callback().
780 • "colors" - An arrayref of colors that are fixed. Note that some
782 color generators will ignore this. If this is supplied it will be
783 filled with the color table generated for the image.
784 • "transp" - The type of transparency processing to perform for
786 images with an alpha channel where the output format does not have
787 a proper alpha channel (eg. GIF). This can be any of:
788 • "none" - No transparency processing is done. (default)
790 • "threshold" - pixels more transparent than "tr_threshold" are
792 rendered as transparent.
793 • "errdiff" - An error diffusion dither is done on the alpha
795 channel. Note that this is independent of the translation
796 performed on the color channels, so some combinations may cause
797 undesired artifacts.
798 • "ordered" - the ordered dither specified by tr_orddith is
800 performed on the alpha channel.
801 This will only be used if the image has an alpha channel, and if
803 there is space in the palette for a transparency color.
804 • "tr_threshold" - the highest alpha value at which a pixel will be
806 made transparent when "transp" is 'threshold'. (0-255, default 127)
807 • "tr_errdiff" - The type of error diffusion to perform on the alpha
809 channel when "transp" is "errdiff". This can be any defined error
810 diffusion type except for custom (see "errdiff" below).
811 • "tr_orddith" - The type of ordered dither to perform on the alpha
813 channel when "transp" is 'ordered'. Possible values are:
814 • "random" - A semi-random map is used. The map is the same each
816 time.
817 • "dot8" - 8x8 dot dither.
819 • "dot4" - 4x4 dot dither
821 • "hline" - horizontal line dither.
823 • "vline" - vertical line dither.
825 • "/line", "slashline" - diagonal line dither
827 • "\line", "backline" - diagonal line dither
829 • "tiny" - dot matrix dither (currently the default). This is
831 probably the best for displays (like web pages).
832 • "custom" - A custom dither matrix is used - see "tr_map".
834 • "tr_map" - When tr_orddith is custom this defines an 8 x 8 matrix
836 of integers representing the transparency threshold for pixels
837 corresponding to each position. This should be a 64 element array
838 where the first 8 entries correspond to the first row of the
839 matrix. Values should be between 0 and 255.
840 • "make_colors" - Defines how the quantization engine will build the
842 palette(s). Currently this is ignored if "translate" is "giflib",
843 but that may change. Possible values are:
844 • "none" - only colors supplied in 'colors' are used.
846 • "webmap" - the web color map is used (need URL here.)
848 • "addi" - The original code for generating the color map (Addi's
850 code) is used.
851 • "mediancut" - Uses a median-cut algorithm, faster than "addi",
853 but not as good a result.
854 • "mono", "monochrome" - a fixed black and white palette,
856 suitable for producing bi-level images (eg. facsimile)
857 • "gray", "gray4", "gray16" - make fixed gray palette with 256, 4
859 or 16 entries respectively.
860 Other methods may be added in the future.
862 • "colors" - an arrayref containing Imager::Color objects, which
864 represents the starting set of colors to use in translating the
865 images. "webmap" will ignore this. On return the final colors
866 used are copied back into this array (which is expanded if
867 necessary.)
868 • "max_colors" - the maximum number of colors to use in the image.
870 • "translate" - The method used to translate the RGB values in the
872 source image into the colors selected by make_colors. Note that
873 make_colors is ignored when "translate" is "giflib".
874 Possible values are:
876 • "giflib" - this is a historical equivalent for "closest" that
878 also forces "make_colors" to "mediancut".
879 • "closest" - the closest color available is used.
881 • "perturb" - the pixel color is modified by "perturb", and the
883 closest color is chosen.
884 • "errdiff" - an error diffusion dither is performed. If the
886 supplied (or generated) palette contains only grays the source
887 colors are converted to gray before error diffusion is
888 performed.
889 It's possible other "translate" values will be added.
891 • "errdiff" - The type of error diffusion dither to perform. These
893 values (except for custom) can also be used in tr_errdif.
894 • "floyd" - Floyd-Steinberg dither
896 • "jarvis" - Jarvis, Judice and Ninke dither
898 • "stucki" - Stucki dither
900 • "custom" - custom. If you use this you must also set
902 "errdiff_width", "errdiff_height" and "errdiff_map".
903 • "errdiff_width", "errdiff_height", "errdiff_orig", "errdiff_map" -
905 When "translate" is "errdiff" and "errdiff" is "custom" these
906 define a custom error diffusion map. "errdiff_width" and
907 "errdiff_height" define the size of the map in the arrayref in
908 "errdiff_map". "errdiff_orig" is an integer which indicates the
909 current pixel position in the top row of the map.
910 • "perturb" - When translate is "perturb" this is the magnitude of
912 the random bias applied to each channel of the pixel before it is
913 looked up in the color table.
914
916 This documents the Imager initialization function, which you will
917 almost never need to call.
918 init()
920 This is a function, not a method.
921 This function is a mess, it can take the following named
923 parameters:
924 • "log" - name of a log file to log Imager's actions to. Not all
926 actions are logged, but the debugging memory allocator does log
927 allocations here. Ignored if Imager has been built without
928 logging support. Preferably use the open_log() method instead.
929 • "loglevel" - the maximum level of message to log. Default: 1.
931 • "warn_obsolete" - if this is non-zero then Imager will warn
933 when you attempt to use obsoleted parameters or functionality.
934 This currently only includes the old GIF output options instead
935 of tags.
936 • "t1log" - if non-zero then T1lib will be configured to produce
938 a log file. This will fail if there are any existing T1lib
939 font objects.
940 Example:
942 Imager::init(log => 'trace.log', loglevel => 9);
944
946 Imager can open an internal log to send debugging information to. This
947 log is extensively used in Imager's tests, but you're unlikely to use
948 it otherwise.
949 If Imager has been built with logging disabled, the methods fail
951 quietly.
952 open_log()
954 Open the Imager debugging log file.
955 • "log" - the file name to log to. If this is undef logging
957 information is sent to the standard error stream.
958 • "loglevel" the level of logging to produce. Default: 1.
960 Returns a true value if the log file was opened successfully.
962 # send debug output to test.log
964 Imager->open_log(log => "test.log");
965 # send debug output to stderr
967 Imager->open_log();
968 close_log()
970 Close the Imager debugging log file and disable debug logging.
971 No parameters.
973 Imager->close_log();
975 log()
977 Imager->log($message)
978 Imager->log($message, $level)
979 This method does not use named parameters.
981 The default for $level is 1.
983 Send a message to the debug log.
985 Imager->log("My code got here!");
987 is_logging()
989 Returns a true value if logging is enabled.
990
992 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
993
995 Imager(3), Imager::Files(3), Imager::Draw(3), Imager::Color(3),
996 Imager::Fill(3), Imager::Font(3), Imager::Transformations(3),
997 Imager::Engines(3), Imager::Filters(3), Imager::Expr(3),
998 Imager::Matrix2d(3), Imager::Fountain(3)
999perl v5.36.0 2023-01-20 Imager::ImageTypes(3)