3 Imager::ImageTypes - image models for Imager
9 $img = Imager->new(); # Empty image (size is 0 by 0)
10 $img->open(file=>'lena.png',type=>'png'); # Read image from file
12 $img = Imager->new(xsize=>400, ysize=>300); # RGB data
14 $img = Imager->new(xsize=>400, ysize=>300, # Grayscale
17 $img = Imager->new(xsize=>400, ysize=>300, # RGB with alpha
20 $img = Imager->new(xsize=>200, ysize=>200,
21 type=>'paletted'); # paletted image
23 $img = Imager->new(xsize=>200, ysize=>200,
24 bits=>16); # 16 bits/channel rgb
26 $img = Imager->new(xsize=>200, ysize=>200,
27 bits=>'double'); # 'double' floating point
30 $img->img_set(xsize=>500, ysize=>500, # reset the image object
34 # Example getting information about an Imager object
36 print "Image information:\n";
37 print "Width: ", $img->getwidth(), "\n";
38 print "Height: ", $img->getheight(), "\n";
39 print "Channels: ", $img->getchannels(), "\n";
40 print "Bits/Channel: ", $img->bits(), "\n";
41 print "Virtual: ", $img->virtual() ? "Yes" : "No", "\n";
42 my $colorcount = $img->getcolorcount(maxcolors=>512);
43 print "Actual number of colors in image: ";
44 print defined($colorcount) ? $colorcount : ">512", "\n";
45 print "Type: ", $img->type(), "\n";
47 if ($img->type() eq 'direct') {
48 print "Modifiable Channels: ";
50 ($img->getmask() & 1<<$_) ? $_ : ()
51 } 0..$img->getchannels();
56 my $count = $img->colorcount;
57 @colors = $img->getcolors();
58 print "Palette size: $count\n";
59 my $mx = @colors > 4 ? 4 : 0+@colors;
60 print "First $mx entries:\n";
61 for (@colors[0..$mx-1]) {
63 print "(", join(", ", @res[0..$img->getchannels()-1]), ")\n";
67 my @tags = $img->tags();
71 print shift @$_, ": ", join " ", @$_, "\n";
74 print "No tags in image\n";
79 Imager supports two basic models of image:
85 direct color - all samples are stored for every pixel. eg. for an
86 8-bit/sample RGB image, 24 bits are stored for each pixel.
90 paletted - an index into a table of colors is stored for each pixel.
94 Direct color or paletted images can have 1 to 4 samples per color
95 stored. Imager treats these as follows:
101 1 sample per color - gray scale image.
105 2 samples per color - gray scale image with alpha channel, allowing
110 3 samples per color - RGB image.
114 4 samples per color - RGB image with alpha channel, allowing
119 Direct color images can have sample sizes of 8-bits per sample,
120 16-bits per sample or a double precision floating point number per
121 sample (64-bits on many systems).
123 Paletted images are always 8-bits/sample.
125 To query an existing image about it's parameters see the C<bits()>,
126 C<type()>, C<getwidth()>, C<getheight()>, C<getchannels()> and
127 C<virtual()> methods.
129 The coordinate system in Imager has the origin in the upper left
130 corner, see L<Imager::Draw> for details.
132 The alpha channel when one is present is considered unassociated -
133 ie the color data has not been scaled by the alpha channel. Note
134 that not all code follows this (recent) rule, but will over time.
136 =head2 Creating Imager Objects
141 X<new(), Imager methods>
143 $img = Imager->new();
144 $img->read(file=>"alligator.ppm") or die $img->errstr;
146 Here C<new()> creates an empty image with width and height of zero.
147 It's only useful for creating an Imager object to call the read()
150 %opts = (xsize=>300, ysize=>200);
151 $img = Imager->new(%opts); # create direct mode RGBA image
152 $img = Imager->new(%opts, channels=>4); # create direct mode RGBA image
154 You can also read a file from new():
156 $img = Imager->new(file => "someimage.png");
158 The parameters for new are:
164 C<xsize>, C<ysize> - Defines the width and height in pixels of the
165 image. These must be positive.
167 If not supplied then only placeholder object is created, which can be
168 supplied to the C<read()> or C<img_set()> methods.
172 C<channels> - The number of channels for the image. Default 3. Valid
173 values are from 1 to 4.
177 C<model> - this overrides the value, if any, supplied for C<channels>.
178 This can be one of C<gray>, C<graya>, C<rgb> or C<rgba>.
182 C<bits> - The storage type for samples in the image. Default: 8.
189 C<8> - One byte per sample. 256 discrete values.
193 C<16> - 16-bits per sample, 65536 discrete values.
197 C<double> - one C double per sample.
201 Note: you can use any Imager function on any sample size image.
203 Paletted images always use 8 bits/sample.
207 C<type> - either C<'direct'> or C<'paletted'>. Default: C<'direct'>.
209 Direct images store color values for each pixel.
211 Paletted images keep a table of up to 256 colors called the palette,
212 each pixel is represented as an index into that table.
214 In most cases when working with Imager you will want to use the
215 C<direct> image type.
217 If you draw on a C<paletted> image with a color not in the image's
218 palette then Imager will transparently convert it to a C<direct>
223 C<maxcolors> - the maximum number of colors in a paletted image.
224 Default: 256. This must be in the range 1 through 256.
228 C<file>, C<fh>, C<fd>, C<callback>, C<readcb>, or C<io> - specify a
229 file name, filehandle, file descriptor or callback to read image data
230 from. See L<Imager::Files> for details. The typical use is:
232 my $im = Imager->new(file => $filename);
236 C<filetype> - treated as the file format parameter, as for C<type>
237 with the read() method, eg:
239 my $im = Imager->new(file => $filename, filetype => "gif");
241 In most cases Imager will detect the file's format itself.
245 In the simplest case just supply the width and height of the image:
247 # 8 bit/sample, RGB image
248 my $img = Imager->new(xsize => $width, ysize => $height);
250 or if you want an alpha channel:
252 # 8 bits/sample, RGBA image
253 my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
255 Note that it I<is> possible for image creation to fail, for example if
256 channels is out of range, or if the image would take too much memory.
258 To create paletted images, set the 'type' parameter to 'paletted':
260 $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
262 which creates an image with a maximum of 256 colors, which you can
263 change by supplying the C<maxcolors> parameter.
265 For improved color precision you can use the bits parameter to specify
268 $img = Imager->new(xsize=>200, ysize=>200,
269 channels=>3, bits=>16);
271 or for even more precision:
273 $img = Imager->new(xsize=>200, ysize=>200,
274 channels=>3, bits=>'double');
276 to get an image that uses a double for each channel.
278 Note that as of this writing all functions should work on images with
279 more than 8-bits/channel, but many will only work at only
280 8-bit/channel precision.
282 If you want an empty Imager object to call the read() method on, just
283 call new() with no parameters:
285 my $img = Imager->new;
286 $img->read(file=>$filename)
289 Though it's much easier now to just call new() with a C<file>
292 my $img = Imager->new(file => $filename)
293 or die Imager->errstr;
295 If none of C<xsize>, C<ysize>, C<file>, C<fh>, C<fd>, C<callback>,
296 C<readcb>, C<data>, C<io> is supplied, and other parameters I<are> supplied
297 C<< Imager->new >> will return failure rather than returning an empty
303 img_set destroys the image data in the object and creates a new one
304 with the given dimensions and channels. For a way to convert image
305 data between formats see the C<convert()> method.
307 $img->img_set(xsize=>500, ysize=>500, channels=>4);
309 This takes exactly the same parameters as the new() method, excluding
310 those for reading from files.
314 =head2 Image Attribute functions
316 These return basic attributes of an image object.
322 print "Image width: ", $img->getwidth(), "\n";
324 The C<getwidth()> method returns the width of the image. This value
325 comes either from C<new()> with C<xsize>, C<ysize> parameters or from
326 reading data from a file with C<read()>. If called on an image that
327 has no valid data in it like C<Imager-E<gt>new()> returns, the return
328 value of C<getwidth()> is undef.
332 print "Image height: ", $img->getheight(), "\n";
334 Same details apply as for L</getwidth()>.
337 X<getchannels() method>X<methods, getchannels()>
339 print "Image has ",$img->getchannels(), " channels\n";
341 Returns the number of channels in an image.
343 Note: previously the number of channels in an image mapped directly to
344 the color model of the image, ie a 4 channel image was always RGBA.
345 This may change in a future release of Imager.
347 Returns an empty list if the image object is not initialized.
349 =item colorchannels()
350 X<colorchannels() method>X<methods, colorchannels()>
352 Returns the number of color channels.
354 Currently this is always 1 or 3, but may be 0 for some rare images in
355 a future version of Imager.
357 Returns an empty list if the image object is not initialized.
360 X<colormodel method>X<methods, colormodel>
362 Returns the color model of the image, including whether there is an
365 By default this is returned as a string, one of C<unknown>, C<gray>,
366 C<graya>, C<rgb> or C<rgba>.
368 If you call C<colormodel()> with a true numeric parameter:
370 my $model = $img->colormodel(numeric => 1);
372 then the color model is returned as a number, mapped as follows:
383 X<alphachannel() method>X<methods, alphachannel()>
385 Returns the channel index of the alpha channel of the image.
387 This is 1 for grayscale images with alpha, 3 for RGB images with alpha
388 and will return C<undef> for all other images.
390 Returns an empty list if the image object is not initialized.
394 The bits() method retrieves the number of bits used to represent each
395 channel in a pixel, 8 for a normal image, 16 for 16-bit image and
396 'double' for a double/channel image.
398 if ($img->bits eq 8) {
399 # fast but limited to 8-bits/sample
402 # slower but more precise
405 Returns an empty list if the image object is not initialized.
409 The type() method returns either 'direct' for direct color images or
410 'paletted' for paletted images.
412 if ($img->type eq 'paletted') {
414 for my $color ($img->getcolors) {
415 print join(",", $color->rgba), "\n";
419 Returns an empty list if the image object is not initialized.
423 The virtual() method returns non-zero if the image contains no actual
424 pixels, for example masked images.
428 This may also be used for non-native Imager images in the future, for
429 example, for an Imager object that draws on an SDL surface.
433 Tests if the image will be written as a monochrome or bi-level image
434 for formats that support that image organization.
436 In scalar context, returns true if the image is bi-level.
438 In list context returns a list:
440 ($is_bilevel, $zero_is_white) = $img->is_bilevel;
442 An image is considered bi-level, if all of the following are true:
448 the image is a paletted image
452 the image has 1 or 3 channels
456 the image has only 2 colors in the palette
460 those 2 colors are black and white, in either order.
464 If a real bi-level organization image is ever added to Imager, this
465 function will return true for that too.
467 Returns an empty list if the image object is not initialized.
471 =head2 Direct Type Images
473 Direct images store the color value directly for each pixel in the
480 @rgbanames = qw( red green blue alpha );
481 my $mask = $img->getmask();
482 print "Modifiable channels:\n";
483 for (0..$img->getchannels()-1) {
484 print $rgbanames[$_],"\n" if $mask & 1<<$_;
489 C<getmask()> is used to fetch the current channel mask. The mask
490 determines what channels are currently modifiable in the image. The
491 channel mask is an integer value, if the C<i-th> least significant bit
492 is set the C<i-th> channel is modifiable. eg. a channel mask of 0x5
493 means only channels 0 and 2 are writable.
497 $mask = $img->getmask();
498 $img->setmask(mask=>8); # modify alpha only
502 $img->setmask(mask=>$mask); # restore previous mask
504 C<setmask()> is used to set the channel mask of the image. See
505 L</getmask()> for details.
509 =head2 Palette Type Images
511 Paletted images keep an array of up to 256 colors, and each pixel is
512 stored as an index into that array.
514 In general you can work with paletted images in the same way as RGB
515 images, except that if you attempt to draw to a paletted image with a
516 color that is not in the image's palette, the image will be converted
517 to an RGB image. This means that drawing on a paletted image with
518 anti-aliasing enabled will almost certainly convert the image to RGB.
520 Palette management takes place through C<addcolors()>, C<setcolors()>,
521 C<getcolors()> and C<findcolor()>:
527 You can add colors to a paletted image with the addcolors() method:
529 my @colors = ( Imager::Color->new(255, 0, 0),
530 Imager::Color->new(0, 255, 0) );
531 my $index = $img->addcolors(colors=>\@colors);
533 The return value is the index of the first color added, or undef if
534 adding the colors would overflow the palette.
536 The only parameter is C<colors> which must be a reference to an array
537 of Imager::Color objects.
541 $img->setcolors(start=>$start, colors=>\@colors);
543 Once you have colors in the palette you can overwrite them with the
544 C<setcolors()> method: C<setcolors()> returns true on success.
552 start - the first index to be set. Default: 0
556 colors - reference to an array of Imager::Color objects.
562 To retrieve existing colors from the palette use the getcolors() method:
564 # get the whole palette
565 my @colors = $img->getcolors();
567 my $color = $img->getcolors(start=>$index);
568 # get a range of colors
569 my @colors = $img->getcolors(start=>$index, count=>$count);
573 To quickly find a color in the palette use findcolor():
575 my $index = $img->findcolor(color=>$color);
577 which returns undef on failure, or the index of the color.
585 color - an Imager::Color object.
591 Returns the number of colors in the image's palette:
593 my $count = $img->colorcount;
597 Returns the maximum size of the image's palette.
599 my $maxcount = $img->maxcolors;
603 =head2 Color Distribution
607 =item getcolorcount()
609 Calculates the number of colors in an image.
611 The amount of memory used by this is proportional to the number of
612 colors present in the image, so to avoid using too much memory you can
613 supply a maxcolors() parameter to limit the memory used.
615 Note: getcolorcount() treats the image as an 8-bit per sample image.
621 X<maxcolors!getcolorcount>C<maxcolors> - the maximum number of colors to
622 return. Default: unlimited.
626 if (defined($img->getcolorcount(maxcolors=>512)) {
627 print "Less than 512 colors in image\n";
630 =item getcolorusagehash()
632 Calculates a histogram of colors used by the image.
638 X<maxcolors!getcolorusagehash>C<maxcolors> - the maximum number of colors
639 to return. Default: unlimited.
643 Returns a reference to a hash where the keys are the raw color as
644 bytes, and the values are the counts for that color.
646 The alpha channel of the image is ignored. If the image is gray scale
647 then the hash keys will each be a single character.
649 my $colors = $img->getcolorusagehash;
650 my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
651 print "#0000FF used $blue_count times\n";
653 =item getcolorusage()
655 Calculates color usage counts and returns just the counts.
661 X<maxcolors!getcolorusage>C<maxcolors> - the maximum number of colors
662 to return. Default: unlimited.
666 Returns a list of the color frequencies in ascending order.
668 my @counts = $img->getcolorusage;
669 print "The most common color is used $counts[0] times\n";
673 =head2 Conversion Between Image Types
675 Warning: if you draw on a paletted image with colors that aren't in
676 the palette, the image will be internally converted to a normal image.
682 You can create a new paletted image from an existing image using the
683 to_paletted() method:
685 $palimg = $img->to_paletted(\%opts)
687 where %opts contains the options specified under L</Quantization options>.
689 # convert to a paletted image using the web palette
690 # use the closest color to each pixel
691 my $webimg = $img->to_paletted({ make_colors => 'webmap' });
693 # convert to a paletted image using a fairly optimal palette
694 # use an error diffusion dither to try to reduce the average error
695 my $optimag = $img->to_paletted({ make_colors => 'mediancut',
696 translate => 'errdiff' });
700 You can convert a paletted image (or any image) to an 8-bit/channel
703 $rgbimg = $img->to_rgb8;
709 Convert a paletted image (or any image) to a 16-bit/channel RGB image.
711 $rgbimg = $img->to_rgb16;
715 =item to_rgb_double()
717 Convert a paletted image (or any image) to an double/channel direct
720 $rgbimg = $img->to_rgb_double;
726 Creates a masked image. A masked image lets you create an image proxy
727 object that protects parts of the underlying target image.
729 In the discussion below there are 3 image objects involved:
735 the masked image - the return value of the masked() method. Any
736 writes to this image are written to the target image, assuming the
737 mask image allows it.
741 the mask image - the image that protects writes to the target image.
742 Supplied as the C<mask> parameter to the masked() method.
746 the target image - the image you called the masked() method on. Any
747 writes to the masked image end up on this image.
757 mask - the mask image. If not supplied then all pixels in the target
758 image are writable. On each write to the masked image, only pixels
759 that have non-zero in channel 0 of the mask image will be written to
760 the original image. Default: none, if not supplied then no masking is
761 done, but the other parameters are still honored.
765 left, top - the offset of writes to the target image. eg. if you
766 attempt to set pixel (x,y) in the masked image, then pixel (x+left,
767 y+top) will be written to in the original image.
771 bottom, right - the bottom right of the area in the target available
772 from the masked image.
776 Masked images let you control which pixels are modified in an
777 underlying image. Where the first channel is completely black in the
778 mask image, writes to the underlying image are ignored.
780 For example, given a base image called $img:
782 my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
784 # ... draw something on the mask
785 my $maskedimg = $img->masked(mask=>$mask);
787 # now draw on $maskedimg and it will only draw on areas of $img
788 # where $mask is non-zero in channel 0.
790 You can specify the region of the underlying image that is masked
791 using the left, top, right and bottom options.
793 If you just want a subset of the image, without masking, just specify
794 the region without specifying a mask. For example:
796 # just work with a 100x100 region of $img
797 my $maskedimg = $img->masked(left => 100, top=>100,
798 right=>200, bottom=>200);
802 This doesn't perform an image conversion, but it can be used to
803 construct a common palette for use in several images:
805 my @colors = Imager->make_palette(\%opts, @images);
807 You must supply at least one image, even if the C<make_colors>
808 parameter produces a fixed palette.
810 On failure returns no colors and you can check C<< Imager->errstr >>.
816 Image tags contain meta-data about the image, ie. information not
817 stored as pixels of the image.
819 At the perl level each tag has a name or code and a value, which is an
820 integer or an arbitrary string. An image can contain more than one
821 tag with the same name or code, but having more than one tag with the
822 same name is discouraged.
824 You can retrieve tags from an image using the tags() method, you can
825 get all of the tags in an image, as a list of array references, with
826 the code or name of the tag followed by the value of the tag.
828 Imager's support for fairly limited, for access to pretty much all
829 image metadata you may want to try L<Image::ExifTool>.
835 Retrieve tags from the image.
837 With no parameters, retrieves a list array references, each containing
838 a name and value: all tags in the image:
840 # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
841 my @alltags = $img->tags;
842 print $_->[0], ":", $_->[1], "\n" for @all_tags;
844 # or put it in a hash, but this will lose duplicates
845 my %alltags = map @$_, $img->tags;
847 in scalar context this returns the number of tags:
849 my $num_tags = $img->tags;
851 or you can get all tags values for the given name:
853 my @namedtags = $img->tags(name => $name);
855 in scalar context this returns the first tag of that name:
857 my $firstnamed = $img->tags(name => $name);
861 my @tags = $img->tags(code=>$code);
865 You can add tags using the addtag() method, either by name:
867 my $index = $img->addtag(name=>$name, value=>$value);
871 my $index = $img->addtag(code=>$code, value=>$value);
875 You can remove tags with the deltag() method, either by index:
877 $img->deltag(index=>$index);
881 $img->deltag(name=>$name);
885 $img->deltag(code=>$code);
887 In each case deltag() returns the number of tags deleted.
891 settag() replaces any existing tags with a new tag. This is
892 equivalent to calling deltag() then addtag().
898 Many tags are only meaningful for one format. GIF looping information
899 is pretty useless for JPEG for example. Thus, many tags are set by
900 only a single reader or used by a single writer. For a complete list
901 of format specific tags see L<Imager::Files>.
903 Since tags are a relatively new addition their use is not wide spread
904 but eventually we hope to have all the readers for various formats set
905 some standard information.
911 X<i_xres tag>X<i_yres tag>X<tags, i_xres>X<tags, i_yres>C<i_xres>, C<i_yres>
912 - The spatial resolution of the image in pixels per inch. If the
913 image format uses a different scale, eg. pixels per meter, then this
914 value is converted. A floating point number stored as a string.
916 # our image was generated as a 300 dpi image
917 $img->settag(name => 'i_xres', value => 300);
918 $img->settag(name => 'i_yres', value => 300);
920 # 100 pixel/cm for a TIFF image
921 $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
922 # convert to pixels per inch, Imager will convert it back
923 $img->settag(name => 'i_xres', value => 100 * 2.54);
924 $img->settag(name => 'i_yres', value => 100 * 2.54);
928 X<i_aspect_only tag>X<tags, i_aspect_only>C<i_aspect_only> - If this is
929 non-zero then the values in i_xres and i_yres are treated as a ratio
930 only. If the image format does not support aspect ratios then this is
931 scaled so the smaller value is 72 DPI.
935 X<i_incomplete tag>X<tags, i_incomplete>C<i_incomplete> - If this tag is
936 present then the whole image could not be read. This isn't
937 implemented for all images yet, and may not be.
941 X<i_lines_read tag>X<tags, i_lines_read>C<i_lines_read> - If
942 C<i_incomplete> is set then this tag may be set to the number of
943 scan lines successfully read from the file. This can be used to decide
944 whether an image is worth processing.
948 X<i_format tag>X<tags, i_format>i_format - The file format this file
953 X<i_background>X<tags, i_background>i_background - used when writing
954 an image with an alpha channel to a file format that doesn't support
955 alpha channels. The C<write> method will convert a normal color
956 specification like "#FF0000" into a color object for you, but if you
957 set this as a tag you will need to format it like
958 C<color(>I<red>C<,>I<green>C<,>I<blue>C<)>, eg color(255,0,0).
962 X<i_comment>C<i_comment> - used when reading or writing several image
963 formats. If the format has only one text field it will be read into
964 the C<i_comment> tag or written to the file.
968 =head2 Quantization options
970 These options can be specified when calling
971 L<Imager::ImageTypes/to_paletted()>, write_multi() for GIF files, when
972 writing a single image with the C<gifquant> option set to C<gen>, or for
973 direct calls to i_writegif_gen() and i_writegif_callback().
979 C<colors> - An arrayref of colors that are fixed. Note that some
980 color generators will ignore this. If this is supplied it will be
981 filled with the color table generated for the image.
985 C<transp> - The type of transparency processing to perform for images
986 with an alpha channel where the output format does not have a proper
987 alpha channel (eg. GIF). This can be any of:
993 C<none> - No transparency processing is done. (default)
997 C<threshold> - pixels more transparent than C<tr_threshold> are
998 rendered as transparent.
1002 C<errdiff> - An error diffusion dither is done on the alpha channel.
1003 Note that this is independent of the translation performed on the
1004 color channels, so some combinations may cause undesired artifacts.
1008 C<ordered> - the ordered dither specified by tr_orddith is performed
1009 on the alpha channel.
1013 This will only be used if the image has an alpha channel, and if there
1014 is space in the palette for a transparency color.
1018 C<tr_threshold> - the highest alpha value at which a pixel will be
1019 made transparent when C<transp> is 'threshold'. (0-255, default 127)
1023 C<tr_errdiff> - The type of error diffusion to perform on the alpha
1024 channel when C<transp> is C<errdiff>. This can be any defined error
1025 diffusion type except for custom (see C<errdiff> below).
1029 C<tr_orddith> - The type of ordered dither to perform on the alpha
1030 channel when C<transp> is 'ordered'. Possible values are:
1036 C<random> - A semi-random map is used. The map is the same each time.
1040 C<dot8> - 8x8 dot dither.
1044 C<dot4> - 4x4 dot dither
1048 C<hline> - horizontal line dither.
1052 C<vline> - vertical line dither.
1056 C</line>, C<slashline> - diagonal line dither
1060 C<\line>, C<backline> - diagonal line dither
1064 C<tiny> - dot matrix dither (currently the default). This is probably
1065 the best for displays (like web pages).
1069 C<custom> - A custom dither matrix is used - see C<tr_map>.
1075 C<tr_map> - When tr_orddith is custom this defines an 8 x 8 matrix of
1076 integers representing the transparency threshold for pixels
1077 corresponding to each position. This should be a 64 element array
1078 where the first 8 entries correspond to the first row of the matrix.
1079 Values should be between 0 and 255.
1083 C<make_colors> - Defines how the quantization engine will build the
1084 palette(s). Currently this is ignored if C<translate> is C<giflib>,
1085 but that may change. Possible values are:
1091 C<none> - only colors supplied in 'colors' are used.
1095 C<webmap> - the web color map is used (need URL here.)
1099 C<addi> - The original code for generating the color map (Addi's code) is
1104 C<mediancut> - Uses a median-cut algorithm, faster than C<addi>, but not
1109 C<mono>, C<monochrome> - a fixed black and white palette, suitable for
1110 producing bi-level images (eg. facsimile)
1114 C<gray>, C<gray4>, C<gray16> - make fixed gray palette with 256, 4 or
1115 16 entries respectively.
1119 Other methods may be added in the future.
1123 C<colors> - an arrayref containing Imager::Color objects, which
1124 represents the starting set of colors to use in translating the
1125 images. C<webmap> will ignore this. On return the final colors used
1126 are copied back into this array (which is expanded if necessary.)
1130 C<max_colors> - the maximum number of colors to use in the image.
1134 C<translate> - The method used to translate the RGB values in the
1135 source image into the colors selected by make_colors. Note that
1136 make_colors is ignored when C<translate> is C<giflib>.
1138 Possible values are:
1144 C<giflib> - this is a historical equivalent for C<closest> that also
1145 forces C<make_colors> to C<mediancut>.
1149 C<closest> - the closest color available is used.
1153 C<perturb> - the pixel color is modified by C<perturb>, and the
1154 closest color is chosen.
1158 C<errdiff> - an error diffusion dither is performed. If the supplied
1159 (or generated) palette contains only grays the source colors are
1160 converted to gray before error diffusion is performed.
1164 It's possible other C<translate> values will be added.
1168 C<errdiff> - The type of error diffusion dither to perform. These
1169 values (except for custom) can also be used in tr_errdif.
1171 =for stopwords Floyd-Steinberg Jarvis Judice Ninke Stucki
1177 C<floyd> - Floyd-Steinberg dither
1181 C<jarvis> - Jarvis, Judice and Ninke dither
1185 C<stucki> - Stucki dither
1189 C<custom> - custom. If you use this you must also set C<errdiff_width>,
1190 C<errdiff_height> and C<errdiff_map>.
1196 C<errdiff_width>, C<errdiff_height>, C<errdiff_orig>, C<errdiff_map> -
1197 When C<translate> is C<errdiff> and C<errdiff> is C<custom> these
1198 define a custom error diffusion map. C<errdiff_width> and
1199 C<errdiff_height> define the size of the map in the arrayref in
1200 C<errdiff_map>. C<errdiff_orig> is an integer which indicates the
1201 current pixel position in the top row of the map.
1205 C<perturb> - When translate is C<perturb> this is the magnitude of the
1206 random bias applied to each channel of the pixel before it is looked
1207 up in the color table.
1211 =head1 INITIALIZATION
1213 This documents the Imager initialization function, which you will
1214 almost never need to call.
1220 This is a function, not a method.
1222 This function is a mess, it can take the following named parameters:
1228 C<log> - name of a log file to log Imager's actions to. Not all
1229 actions are logged, but the debugging memory allocator does log
1230 allocations here. Ignored if Imager has been built without logging
1231 support. Preferably use the open_log() method instead.
1235 C<loglevel> - the maximum level of message to log. Default: 1.
1239 C<warn_obsolete> - if this is non-zero then Imager will warn when you
1240 attempt to use obsoleted parameters or functionality. This currently
1241 only includes the old GIF output options instead of tags.
1245 C<t1log> - if non-zero then T1lib will be configured to produce a log
1246 file. This will fail if there are any existing T1lib font objects.
1252 Imager::init(log => 'trace.log', loglevel => 9);
1256 =head1 LOGGING METHODS
1258 Imager can open an internal log to send debugging information to.
1259 This log is extensively used in Imager's tests, but you're unlikely to
1262 If Imager has been built with logging disabled, the methods fail
1269 Open the Imager debugging log file.
1275 C<log> - the file name to log to. If this is undef logging information
1276 is sent to the standard error stream.
1280 C<loglevel> the level of logging to produce. Default: 1.
1284 Returns a true value if the log file was opened successfully.
1286 # send debug output to test.log
1287 Imager->open_log(log => "test.log");
1289 # send debug output to stderr
1294 Close the Imager debugging log file and disable debug logging.
1298 Imager->close_log();
1302 Imager->log($message)
1303 Imager->log($message, $level)
1305 This method does not use named parameters.
1307 The default for C<$level> is 1.
1309 Send a message to the debug log.
1311 Imager->log("My code got here!");
1315 Returns a true value if logging is enabled.
1321 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
1325 Imager(3), Imager::Files(3), Imager::Draw(3),
1326 Imager::Color(3), Imager::Fill(3), Imager::Font(3),
1327 Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
1328 Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)