the rubthrough() method now supports destination images with an alpha
[imager.git] / lib / Imager / ImageTypes.pod
CommitLineData
83dadefe
AMH
1=head1 NAME
2
3d24c832 3Imager::ImageTypes - image models for Imager
83dadefe
AMH
4
5=head1 SYNOPSIS
6
7 use Imager;
8
9 $img = Imager->new(); # Empty image (size is 0 by 0)
10 $img->open(file=>'lena.png',type=>'png'); # Read image from file
11
12 $img = Imager->new(xsize=>400, ysize=>300); # RGB data
83dadefe 13
5df0fac7
AMH
14 $img = Imager->new(xsize=>400, ysize=>300, # Grayscale
15 channels=>1); #
16
17 $img = Imager->new(xsize=>400, ysize=>300, # RGB with alpha
18 channels=>4); #
19
20 $img = Imager->new(xsize=>200, ysize=>200,
21 type=>'paletted'); # paletted image
22
23 $img = Imager->new(xsize=>200, ysize=>200,
24 bits=>16); # 16 bits/channel rgb
25
26 $img = Imager->new(xsize=>200, ysize=>200,
27 bits=>'double'); # 'double' floating point
28 # per channel
29
30 $img->img_set(xsize=>500, ysize=>500, # reset the image object
31 channels=>4);
32
33
34 # Example getting information about an Imager object
35
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";
46
47 if ($img->type() eq 'direct') {
48 print "Modifiable Channels: ";
49 print join " ", map {
50 ($img->getmask() & 1<<$_) ? $_ : ()
51 } 0..$img->getchannels();
52 print "\n";
53
54 } else {
feac660c
TC
55 # palette info
56 my $count = $img->colorcount;
5df0fac7 57 @colors = $img->getcolors();
feac660c 58 print "Palette size: $count\n";
5df0fac7
AMH
59 my $mx = @colors > 4 ? 4 : 0+@colors;
60 print "First $mx entries:\n";
61 for (@colors[0..$mx-1]) {
62 my @res = $_->rgba();
63 print "(", join(", ", @res[0..$img->getchannels()-1]), ")\n";
64 }
65 }
66
67 my @tags = $img->tags();
68 if (@tags) {
69 print "Tags:\n";
70 for(@tags) {
71 print shift @$_, ": ", join " ", @$_, "\n";
72 }
73 } else {
74 print "No tags in image\n";
75 }
76
5df0fac7 77=head1 DESCRIPTION
83dadefe 78
3d24c832
TC
79Imager supports two basic models of image:
80
81=over
82
83=item *
84
85direct color - all samples are stored for every pixel. eg. for an
868-bit/sample RGB image, 24 bits are stored for each pixel.
87
88=item *
89
90paletted - an index into a table of colors is stored for each pixel.
91
92=back
93
94Direct color or paletted images can have 1 to 4 samples per color
95stored. Imager treats these as follows:
96
97=over
98
99=item *
100
1011 sample per color - grayscale image.
102
103=item *
104
1052 samples per color - grayscale image with alpha channel.
106
107=item *
108
1093 samples per color - RGB image.
110
111=item *
112
1134 samples per color - RGB image with alpha channel.
114
115=back
116
117Direct color images can have sample sizes of 8-bits per sample,
11816-bits per sample or a double precision floating point number per
119sample (64-bits on many systems).
120
121Paletted images are always 8-bits/sample.
83dadefe 122
5df0fac7
AMH
123To query an existing image about it's parameters see the C<bits()>,
124C<type()>, C<getwidth()>, C<getheight()>, C<getchannels()> and
125C<virtual()> methods.
83dadefe
AMH
126
127The coordinate system in Imager has the origin in the upper left
128corner, see L<Imager::Draw> for details.
129
fe415ad2
TC
130The alpha channel when one is present is considered unassociated -
131ie. the color data has not been scaled by the alpha channel. Note
132that not all code follows this (recent) rule, but will over time.
133
5df0fac7 134=head2 Creating Imager Objects
83dadefe
AMH
135
136=over
137
138=item new
139
140 $img = Imager->new();
141 $img->read(file=>"alligator.ppm") or die $img->errstr;
142
143Here C<new()> creates an empty image with width and height of zero.
144It's only useful for creating an Imager object to call the read()
145method on later.
146
147 %opts = (xsize=>300, ysize=>200);
148 $img = Imager->new(%opts); # create direct mode RGBA image
149 $img = Imager->new(%opts, channels=>4); # create direct mode RGBA image
150
4b3408a5
TC
151The parameters for new are:
152
153=over
154
155=item *
156
157C<xsize>, C<ysize> - Defines the width and height in pixels of the
158image. These must be positive.
159
160If not supplied then only placeholder object is created, which can be
161supplied to the C<read()> or C<img_set()> methods.
162
163=item *
164
165C<channels> - The number of channels for the image. Default 3. Valid
166values are from 1 to 4.
167
168=item *
169
170C<bits> - The storage type for samples in the image. Default: 8.
171Valid values are:
172
173=over
174
175=item *
176
177C<8> - One byte per sample. 256 discrete values.
178
179=item *
180
181C<16> - 16-bits per sample, 65536 discrete values.
182
183=item *
184
185C<double> - one C double per sample.
186
187=back
188
189Note: you can use any Imager function on any sample size image.
190
191Paletted images always use 8 bits/sample.
192
193=item *
194
195C<type> - either C<'direct'> or C<'paletted'>. Default: C<'direct'>.
196
197Direct images store color values for each pixel.
198
199Paletted images keep a table of up to 256 colors called the palette,
200each pixel is represented as an index into that table.
201
202In most cases when working with Imager you will want to use the
203C<direct> image type.
204
205If you draw on a C<paletted> image with a color not in the image's
206palette then Imager will transparently convert it to a C<direct>
207image.
208
209=item *
210
211C<maxcolors> - the maximum number of colors in a paletted image.
212Default: 256. This must be in the range 1 through 256.
213
214=back
215
216In the simplest case just supply the width and height of the image:
217
218 # 8 bit/sample, RGB image
219 my $img = Imager->new(xsize => $width, ysize => $height);
220
221or if you want an alpha channel:
222
223 # 8 bits/sample, RGBA image
224 my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
225
226Note that it I<is> possible for image creation to fail, for example if
227channels is out of range, or if the image would take too much memory.
228
83dadefe
AMH
229To create paletted images, set the 'type' parameter to 'paletted':
230
231 $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
232
233which creates an image with a maxiumum of 256 colors, which you can
234change by supplying the C<maxcolors> parameter.
235
236For improved color precision you can use the bits parameter to specify
23716 bit per channel:
238
5df0fac7
AMH
239 $img = Imager->new(xsize=>200, ysize=>200,
240 channels=>3, bits=>16);
83dadefe
AMH
241
242or for even more precision:
243
5df0fac7
AMH
244 $img = Imager->new(xsize=>200, ysize=>200,
245 channels=>3, bits=>'double');
83dadefe
AMH
246
247to get an image that uses a double for each channel.
248
249Note that as of this writing all functions should work on images with
250more than 8-bits/channel, but many will only work at only
2518-bit/channel precision.
252
4b3408a5
TC
253If you want an empty Imager object to call the read() method on, just
254call new() with no parameters:
255
256 my $img = Imager->new;
257 $img->read(file=>$filename)
258 or die $img->errstr;
83dadefe
AMH
259
260=item img_set
261
23bf355e
AMH
262img_set destroys the image data in the object and creates a new one
263with the given dimensions and channels. For a way to convert image
264data between formats see the C<convert()> method.
83dadefe
AMH
265
266 $img->img_set(xsize=>500, ysize=>500, channels=>4);
267
4b3408a5
TC
268This takes exactly the same parameters as the new() method.
269
83dadefe
AMH
270=back
271
5df0fac7 272=head2 Getting Information About an Imager Object
83dadefe 273
5df0fac7 274=over
83dadefe 275
5df0fac7 276=item getwidth
83dadefe 277
5df0fac7 278 print "Image width: ", $img->getwidth(), "\n";
83dadefe 279
5df0fac7
AMH
280The C<getwidth()> method returns the width of the image. This value
281comes either from C<new()> with xsize,ysize parameters or from reading
282data from a file with C<read()>. If called on an image that has no
23bf355e
AMH
283valid data in it like C<Imager-E<gt>new()> returns, the return value
284of C<getwidth()> is undef.
83dadefe 285
5df0fac7
AMH
286=item getheight
287
288 print "Image height: ", $img->getheight(), "\n";
289
290Same details apply as for L<getwidth>.
83dadefe
AMH
291
292=item getchannels
293
5df0fac7
AMH
294 print "Image has ",$img->getchannels(), " channels\n";
295
83dadefe
AMH
296To get the number of channels in an image C<getchannels()> is used.
297
83dadefe 298
5df0fac7
AMH
299=item getcolorcount
300
301It is possible to have Imager find the number of colors in an image by
302with the C<getcolorcount()> method. It requires memory proportionally
303to the number of colors in the image so it is possible to have it stop
304sooner if you only need to know if there are more than a certain
305number of colors in the image. If there are more colors than asked
306for the function return undef. Examples:
307
23bf355e 308 if (defined($img->getcolorcount(maxcolors=>512)) {
5df0fac7
AMH
309 print "Less than 512 colors in image\n";
310 }
311
312
313=item bits
314
315The bits() method retrieves the number of bits used to represent each
316channel in a pixel, 8 for a normal image, 16 for 16-bit image and
317'double' for a double/channel image.
318
4b3408a5
TC
319 if ($img->bits eq 8) {
320 # fast but limited to 8-bits/sample
321 }
322 else {
323 # slower but more precise
324 }
325
5df0fac7
AMH
326=item type
327
328The type() method returns either 'direct' for truecolor images or
4b3408a5
TC
329'paletted' for paletted images.
330
331 if ($img->type eq 'paletted') {
332 # print the palette
333 for my $color ($img->getcolors) {
334 print join(",", $color->rgba), "\n";
335 }
336 }
5df0fac7
AMH
337
338=item virtual
339
dab402c3
AMH
340The virtual() method returns non-zero if the image contains no actual
341pixels, for example masked images.
5df0fac7 342
4b3408a5
TC
343This may also be used for non-native Imager images in the future, for
344example, for an Imager object that draws on an SDL surface.
5df0fac7 345
4b3408a5 346=back
5df0fac7
AMH
347
348=head2 Direct Type Images
349
4b3408a5
TC
350Direct images store the color value directly for each pixel in the
351image.
352
5df0fac7
AMH
353=over
354
355=item getmask
356
357 @rgbanames = qw( red green blue alpha );
358 my $mask = $img->getmask();
359 print "Modifiable channels:\n";
360 for (0..$img->getchannels()-1) {
361 print $rgbanames[$_],"\n" if $mask & 1<<$_;
362 }
363
364C<getmask()> is used to fetch the current channel mask. The mask
365determines what channels are currently modifiable in the image. The
366channel mask is an integer value, if the i-th lsb is set the i-th
4b3408a5
TC
367channel is modifiable. eg. a channel mask of 0x5 means only channels
3680 and 2 are writable.
5df0fac7
AMH
369
370=item setmask
371
372 $mask = $img->getmask();
373 $img->setmask(mask=>8); # modify alpha only
374
375 ...
83dadefe 376
83dadefe
AMH
377 $img->setmask(mask=>$mask); # restore previous mask
378
5df0fac7
AMH
379C<setmask()> is used to set the channel mask of the image. See
380L<getmask> for details.
83dadefe
AMH
381
382=back
383
5df0fac7 384=head2 Palette Type Images
83dadefe 385
4b3408a5
TC
386Paletted images keep an array of up to 256 colors, and each pixel is
387stored as an index into that array.
388
83dadefe
AMH
389In general you can work with paletted images in the same way as RGB
390images, except that if you attempt to draw to a paletted image with a
391color that is not in the image's palette, the image will be converted
392to an RGB image. This means that drawing on a paletted image with
393anti-aliasing enabled will almost certainly convert the image to RGB.
394
395Palette management takes place through C<addcolors()>, C<setcolors()>,
396C<getcolors()> and C<findcolor()>:
397
398=over
399
400=item addcolors
401
402You can add colors to a paletted image with the addcolors() method:
403
404 my @colors = ( Imager::Color->new(255, 0, 0),
405 Imager::Color->new(0, 255, 0) );
406 my $index = $img->addcolors(colors=>\@colors);
407
408The return value is the index of the first color added, or undef if
409adding the colors would overflow the palette.
410
4b3408a5
TC
411The only parameter is C<colors> which must be a reference to an array
412of Imager::Color objects.
413
83dadefe
AMH
414=item setcolors
415
83dadefe
AMH
416 $img->setcolors(start=>$start, colors=>\@colors);
417
5df0fac7 418Once you have colors in the palette you can overwrite them with the
1501d9b3 419C<setcolors()> method: C<setcolors()> returns true on success.
83dadefe 420
4b3408a5
TC
421Parameters:
422
423=over
424
425=item *
426
427start - the first index to be set. Default: 0
428
429=item *
430
431colors - reference to an array of Imager::Color objects.
432
433=back
434
83dadefe
AMH
435=item getcolors
436
437To retrieve existing colors from the palette use the getcolors() method:
438
439 # get the whole palette
440 my @colors = $img->getcolors();
441 # get a single color
442 my $color = $img->getcolors(start=>$index);
443 # get a range of colors
444 my @colors = $img->getcolors(start=>$index, count=>$count);
445
446=item findcolor
447
448To quickly find a color in the palette use findcolor():
449
450 my $index = $img->findcolor(color=>$color);
451
452which returns undef on failure, or the index of the color.
453
4b3408a5
TC
454Parameter:
455
456=over
457
458=item *
459
460color - an Imager::Color object.
461
462=back
463
feac660c
TC
464=item colorcount
465
466Returns the number of colors in the image's palette:
467
468 my $count = $img->colorcount;
469
470=item maxcolors
471
472Returns the maximum size of the image's palette.
473
474 my $maxcount = $img->maxcolors;
83dadefe
AMH
475
476=back
477
478=head2 Conversion Between Image Types
479
5df0fac7
AMH
480Warning: if you draw on a paletted image with colors that aren't in
481the palette, the image will be internally converted to a normal image.
482
83dadefe
AMH
483=over
484
485=item to_paletted
486
487You can create a new paletted image from an existing image using the
488to_paletted() method:
489
490 $palimg = $img->to_paletted(\%opts)
491
492where %opts contains the options specified under L<Quantization options>.
493
4b3408a5
TC
494 # convert to a paletted image using the web palette
495 # use the closest color to each pixel
496 my $webimg = $img->to_paletted({ make_colors => 'webmap' });
497
498 # convert to a paletted image using a fairly optimal palette
499 # use an error diffusion dither to try to reduce the average error
500 my $optimag = $img->to_paletted({ make_colors => 'mediancut',
501 translate => 'errdiff' });
502
83dadefe
AMH
503=item to_rgb8
504
505You can convert a paletted image (or any image) to an 8-bit/channel
506RGB image with:
507
508 $rgbimg = $img->to_rgb8;
509
4b3408a5
TC
510No parameters.
511
512=item masked
513
514Creates a masked image. A masked image lets you create an image proxy
515object that protects parts of the underlying target image.
516
517In the discussion below there are 3 image objects involved:
518
519=over
520
521=item *
522
523the masked image - the return value of the masked() method. Any
524writes to this image are written to the target image, assuming the
525mask image allows it.
526
527=item *
528
529the mask image - the image that protects writes to the target image.
530Supplied as the C<mask> parameter to the masked() method.
531
532=item *
533
534the target image - the image you called the masked() method on. Any
535writes to the masked image end up on this image.
536
537=back
538
539Parameters:
540
541=over
542
543=item *
544
545mask - the mask image. If not supplied then all pixels in the target
546image are writable. On each write to the masked image, only pixels
547that have non-zero in chennel 0 of the mask image will be written to
548the original image. Default: none, if not supplied then no masking is
549done, but the other parameters are still honored.
83dadefe 550
4b3408a5
TC
551=item *
552
553left, top - the offset of writes to the target image. eg. if you
554attempt to set pixel (x,y) in the masked image, then pixel (x+left,
555y+top) will be written to in the original image.
556
557=item *
558
559bottom, right - the bottom right of the area in the target available
560from the masked image.
561
562=back
3e1be2c1
AMH
563
564Masked images let you control which pixels are modified in an
565underlying image. Where the first channel is completely black in the
566mask image, writes to the underlying image are ignored.
567
568For example, given a base image called $img:
569
4b3408a5 570 my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
3e1be2c1
AMH
571 channels=>1);
572 # ... draw something on the mask
573 my $maskedimg = $img->masked(mask=>$mask);
574
4b3408a5
TC
575 # now draw on $maskedimg and it will only draw on areas of $img
576 # where $mask is non-zero in channel 0.
577
3e1be2c1
AMH
578You can specifiy the region of the underlying image that is masked
579using the left, top, right and bottom options.
580
581If you just want a subset of the image, without masking, just specify
4b3408a5 582the region without specifying a mask. For example:
3e1be2c1 583
4b3408a5
TC
584 # just work with a 100x100 region of $img
585 my $maskedimg = $img->masked(left => 100, top=>100,
586 right=>200, bottom=>200);
3e1be2c1 587
4b3408a5 588=back
3e1be2c1 589
5df0fac7 590=head2 Tags
83dadefe 591
5df0fac7
AMH
592Image tags contain meta-data about the image, ie. information not
593stored as pixels of the image.
83dadefe 594
5df0fac7
AMH
595At the perl level each tag has a name or code and a value, which is an
596integer or an arbitrary string. An image can contain more than one
4b3408a5
TC
597tag with the same name or code, but having more than one tag with the
598same name is discouraged.
83dadefe 599
5df0fac7
AMH
600You can retrieve tags from an image using the tags() method, you can
601get all of the tags in an image, as a list of array references, with
4b3408a5
TC
602the code or name of the tag followed by the value of the tag.
603
604=over
605
606=item tags
607
608Retrieve tags from the image.
83dadefe 609
4b3408a5
TC
610With no parameters, retrieves a list array references, each containing
611a name and value: all tags in the image:
612
613 # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
5df0fac7 614 my @alltags = $img->tags;
4b3408a5
TC
615 print $_->[0], ":", $_->[1], "\n" for @all_tags;
616
617 # or put it in a hash, but this will lose duplicates
618 my %alltags = map @$_, $img->tags;
619
620in scalar context this returns the number of tags:
621
622 my $num_tags = $img->tags;
83dadefe 623
4b3408a5 624or you can get all tags values for the given name:
83dadefe 625
4b3408a5
TC
626 my @namedtags = $img->tags(name => $name);
627
628in scalar context this returns the first tag of that name:
629
630 my $firstnamed = $img->tags(name => $name);
83dadefe 631
5df0fac7 632or a given code:
83dadefe 633
5df0fac7 634 my @tags = $img->tags(code=>$code);
83dadefe 635
4b3408a5
TC
636=item addtag
637
5df0fac7 638You can add tags using the addtag() method, either by name:
83dadefe 639
5df0fac7 640 my $index = $img->addtag(name=>$name, value=>$value);
83dadefe 641
5df0fac7 642or by code:
83dadefe 643
5df0fac7 644 my $index = $img->addtag(code=>$code, value=>$value);
83dadefe 645
4b3408a5
TC
646=item deltag
647
5df0fac7 648You can remove tags with the deltag() method, either by index:
83dadefe 649
5df0fac7
AMH
650 $img->deltag(index=>$index);
651
652or by name:
653
654 $img->deltag(name=>$name);
83dadefe 655
5df0fac7 656or by code:
83dadefe 657
5df0fac7 658 $img->deltag(code=>$code);
83dadefe 659
5df0fac7 660In each case deltag() returns the number of tags deleted.
83dadefe 661
58a9ba58
TC
662=item settag
663
664settag() replaces any existing tags with a new tag. This is
665equivalent to calling deltag() then addtag().
666
4b3408a5 667=back
83dadefe 668
5df0fac7
AMH
669=head2 Common Tags
670
671Many tags are only meaningful for one format. GIF looping information
672is pretty useless for JPEG for example. Thus, many tags are set by
673only a single reader or used by a single writer. For a complete list
674of format specific tags see L<Imager::Files>.
675
676Since tags are a relatively new addition their use is not wide spread
677but eventually we hope to have all the readers for various formats set
678some standard information.
679
680=over
83dadefe 681
5df0fac7
AMH
682=item i_xres
683
684=item i_yres
685
686The spatial resolution of the image in pixels per inch. If the image
687format uses a different scale, eg. pixels per meter, then this value
688is converted. A floating point number stored as a string.
689
c2d1dd13
TC
690 # our image was generated as a 300 dpi image
691 $img->settag(name => 'i_xres', value => 300);
692 $img->settag(name => 'i_yres', value => 300);
693
694 # 100 pixel/cm for a TIFF image
695 $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
696 # convert to pixels per inch, Imager will convert it back
697 $img->settag(name => 'i_xres', value => 100 * 2.54);
698 $img->settag(name => 'i_yres', value => 100 * 2.54);
699
5df0fac7
AMH
700=item i_aspect_only
701
702If this is non-zero then the values in i_xres and i_yres are treated
703as a ratio only. If the image format does not support aspect ratios
704then this is scaled so the smaller value is 72dpi.
705
706=item i_incomplete
707
708If this tag is present then the whole image could not be read. This
4b3408a5 709isn't implemented for all images yet, and may not be.
5df0fac7 710
50dc291e 711=item i_format
3e1be2c1 712
50dc291e 713The file format this file was read from.
3e1be2c1 714
50dc291e 715=back
e97f9d6e
AMH
716
717=head2 Quantization options
718
719These options can be specified when calling write_multi() for gif
720files, when writing a single image with the gifquant option set to
721'gen', or for direct calls to i_writegif_gen and i_writegif_callback.
722
723=over
724
725=item colors
726
727A arrayref of colors that are fixed. Note that some color generators
728will ignore this.
729
730=item transp
731
732The type of transparency processing to perform for images with an
733alpha channel where the output format does not have a proper alpha
734channel (eg. gif). This can be any of:
735
736=over
737
738=item none
739
740No transparency processing is done. (default)
741
742=item threshold
743
744Pixels more transparent that tr_threshold are rendered as transparent.
745
746=item errdiff
747
748An error diffusion dither is done on the alpha channel. Note that
749this is independent of the translation performed on the colour
750channels, so some combinations may cause undesired artifacts.
751
752=item ordered
753
754The ordered dither specified by tr_orddith is performed on the alpha
755channel.
756
757=back
758
759This will only be used if the image has an alpha channel, and if there
760is space in the palette for a transparency colour.
761
762=item tr_threshold
763
764The highest alpha value at which a pixel will be made transparent when
765transp is 'threshold'. (0-255, default 127)
766
767=item tr_errdiff
768
769The type of error diffusion to perform on the alpha channel when
770transp is 'errdiff'. This can be any defined error diffusion type
771except for custom (see errdiff below).
772
773=item tr_orddith
774
775The type of ordered dither to perform on the alpha channel when transp
776is 'ordered'. Possible values are:
777
778=over
779
780=item random
781
782A semi-random map is used. The map is the same each time.
783
784=item dot8
785
7868x8 dot dither.
787
788=item dot4
789
7904x4 dot dither
791
792=item hline
793
794horizontal line dither.
795
796=item vline
797
798vertical line dither.
799
800=item "/line"
801
802=item slashline
803
804diagonal line dither
805
806=item '\line'
807
808=item backline
809
810diagonal line dither
811
812=item tiny
813
814dot matrix dither (currently the default). This is probably the best
815for displays (like web pages).
816
817=item custom
818
819A custom dither matrix is used - see tr_map
820
821=back
822
823=item tr_map
824
825When tr_orddith is custom this defines an 8 x 8 matrix of integers
826representing the transparency threshold for pixels corresponding to
827each position. This should be a 64 element array where the first 8
828entries correspond to the first row of the matrix. Values should be
829betweern 0 and 255.
830
831=item make_colors
832
833Defines how the quantization engine will build the palette(s).
834Currently this is ignored if 'translate' is 'giflib', but that may
835change. Possible values are:
836
837=over
838
839=item none
840
841Only colors supplied in 'colors' are used.
842
843=item webmap
844
845The web color map is used (need url here.)
846
847=item addi
848
849The original code for generating the color map (Addi's code) is used.
850
9d1c4956
TC
851=item mediancut
852
853Uses a mediancut algorithm, faster than 'addi', but not as good a
854result.
855
e97f9d6e
AMH
856=back
857
858Other methods may be added in the future.
859
860=item colors
861
862A arrayref containing Imager::Color objects, which represents the
863starting set of colors to use in translating the images. webmap will
864ignore this. The final colors used are copied back into this array
865(which is expanded if necessary.)
866
867=item max_colors
868
869The maximum number of colors to use in the image.
870
871=item translate
872
873The method used to translate the RGB values in the source image into
874the colors selected by make_colors. Note that make_colors is ignored
875whene translate is 'giflib'.
876
877Possible values are:
878
879=over
880
881=item giflib
882
883The giflib native quantization function is used.
884
885=item closest
886
887The closest color available is used.
888
889=item perturb
890
891The pixel color is modified by perturb, and the closest color is chosen.
892
893=item errdiff
894
895An error diffusion dither is performed.
896
897=back
898
899It's possible other transate values will be added.
900
901=item errdiff
902
903The type of error diffusion dither to perform. These values (except
904for custom) can also be used in tr_errdif.
905
906=over
907
908=item floyd
909
910Floyd-Steinberg dither
911
912=item jarvis
913
914Jarvis, Judice and Ninke dither
915
916=item stucki
917
918Stucki dither
919
920=item custom
921
922Custom. If you use this you must also set errdiff_width,
923errdiff_height and errdiff_map.
924
925=back
926
927=item errdiff_width
928
929=item errdiff_height
930
931=item errdiff_orig
932
933=item errdiff_map
934
935When translate is 'errdiff' and errdiff is 'custom' these define a
936custom error diffusion map. errdiff_width and errdiff_height define
937the size of the map in the arrayref in errdiff_map. errdiff_orig is
938an integer which indicates the current pixel position in the top row
939of the map.
940
941=item perturb
942
943When translate is 'perturb' this is the magnitude of the random bias
944applied to each channel of the pixel before it is looked up in the
945color table.
946
947=back
948
d5556805
TC
949=head1 INITIALIZATION
950
951This documents the Imager initialization function, which you will
952almost never need to call.
953
954=over
955
956=item init
957
958This is a function, not a method.
959
960This function is a mess, it can take the following named parameters:
961
962=over
963
964=item *
965
966log - name of a log file to log Imager's actions to. Not all actions
967are logged, but the debugging memory allocator does log allocations
968here. Ignored if Imager has been built without logging support.
969
970=item *
971
972loglevel - the maximum level of message to log. Default: 1.
973
974=item *
975
976warn_obsolete - if this is non-zero then Imager will warn when you
977attempt to use obsoleted parameters or functionality. This currently
978only includes the old gif output options instead of tags.
979
980=item *
981
982t1log - if non-zero then T1lib will be configured to produce a log
983file. This will fail if there are any existing T1lib font objects.
984
985=back
986
987Example:
988
989 Imager::init(log => 'trace.log', loglevel => 9);
990
991=back
992
4b3408a5
TC
993=head1 REVISION
994
995$Revision$
996
997=head1 AUTHORS
998
999Tony Cook, Arnar M. Hrafnkelsson
1000
1001=head1 SEE ALSO
1002
1003Imager(3), Imager::Files(3), Imager::Draw(3),
1004Imager::Color(3), Imager::Fill(3), Imager::Font(3),
1005Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
1006Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)
bac4fcee 1007
9d1c4956 1008=cut