Various changes:
[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
9c106321 682=item *
5df0fac7 683
9c106321
TC
684X<i_xres tag>X<i_yres tag>X<tags, i_xres>X<tags, i_yres>i_xres, i_yres
685- The spatial resolution of the image in pixels per inch. If the
686image format uses a different scale, eg. pixels per meter, then this
687value is converted. A floating point number stored as a string.
5df0fac7 688
c2d1dd13
TC
689 # our image was generated as a 300 dpi image
690 $img->settag(name => 'i_xres', value => 300);
691 $img->settag(name => 'i_yres', value => 300);
692
693 # 100 pixel/cm for a TIFF image
694 $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
695 # convert to pixels per inch, Imager will convert it back
696 $img->settag(name => 'i_xres', value => 100 * 2.54);
697 $img->settag(name => 'i_yres', value => 100 * 2.54);
698
9c106321
TC
699=item *
700
701X<i_aspect_only tag>X<tags, i_aspect_only>i_aspect_only - If this is
702non-zero then the values in i_xres and i_yres are treated as a ratio
703only. If the image format does not support aspect ratios then this is
704scaled so the smaller value is 72dpi.
5df0fac7 705
9c106321
TC
706=item *
707
708X<i_incomplete tag>X<tags, i_incomplete>i_incomplete - If this tag is
709present then the whole image could not be read. This isn't
710implemented for all images yet, and may not be.
5df0fac7 711
9c106321 712=item *
5df0fac7 713
9c106321
TC
714X<i_lines_read tag>X<tags, i_lines_read>i_lines_read - If
715C<i_incomplete> is set then this tag may be set to the number of
716scanlines successfully read from the file. This can be used to decide
717whether an image is worth processing.
5df0fac7 718
9c106321 719=item *
3e1be2c1 720
9c106321
TC
721X<i_format tag>X<tags, i_format>i_format - The file format this file
722was read from.
3e1be2c1 723
50dc291e 724=back
e97f9d6e
AMH
725
726=head2 Quantization options
727
9c106321
TC
728These options can be specified when calling
729L<Imager::ImageTypes/to_paletted>, write_multi() for gif files, when
730writing a single image with the gifquant option set to 'gen', or for
731direct calls to i_writegif_gen and i_writegif_callback.
e97f9d6e
AMH
732
733=over
734
735=item colors
736
737A arrayref of colors that are fixed. Note that some color generators
738will ignore this.
739
740=item transp
741
742The type of transparency processing to perform for images with an
743alpha channel where the output format does not have a proper alpha
744channel (eg. gif). This can be any of:
745
746=over
747
748=item none
749
750No transparency processing is done. (default)
751
752=item threshold
753
754Pixels more transparent that tr_threshold are rendered as transparent.
755
756=item errdiff
757
758An error diffusion dither is done on the alpha channel. Note that
759this is independent of the translation performed on the colour
760channels, so some combinations may cause undesired artifacts.
761
762=item ordered
763
764The ordered dither specified by tr_orddith is performed on the alpha
765channel.
766
767=back
768
769This will only be used if the image has an alpha channel, and if there
770is space in the palette for a transparency colour.
771
772=item tr_threshold
773
774The highest alpha value at which a pixel will be made transparent when
775transp is 'threshold'. (0-255, default 127)
776
777=item tr_errdiff
778
779The type of error diffusion to perform on the alpha channel when
780transp is 'errdiff'. This can be any defined error diffusion type
781except for custom (see errdiff below).
782
783=item tr_orddith
784
785The type of ordered dither to perform on the alpha channel when transp
786is 'ordered'. Possible values are:
787
788=over
789
790=item random
791
792A semi-random map is used. The map is the same each time.
793
794=item dot8
795
7968x8 dot dither.
797
798=item dot4
799
8004x4 dot dither
801
802=item hline
803
804horizontal line dither.
805
806=item vline
807
808vertical line dither.
809
810=item "/line"
811
812=item slashline
813
814diagonal line dither
815
816=item '\line'
817
818=item backline
819
820diagonal line dither
821
822=item tiny
823
824dot matrix dither (currently the default). This is probably the best
825for displays (like web pages).
826
827=item custom
828
829A custom dither matrix is used - see tr_map
830
831=back
832
833=item tr_map
834
835When tr_orddith is custom this defines an 8 x 8 matrix of integers
836representing the transparency threshold for pixels corresponding to
837each position. This should be a 64 element array where the first 8
838entries correspond to the first row of the matrix. Values should be
839betweern 0 and 255.
840
841=item make_colors
842
843Defines how the quantization engine will build the palette(s).
844Currently this is ignored if 'translate' is 'giflib', but that may
845change. Possible values are:
846
847=over
848
9c106321 849=item *
e97f9d6e 850
9c106321 851none - only colors supplied in 'colors' are used.
e97f9d6e 852
9c106321 853=item *
e97f9d6e 854
9c106321 855webmap - the web color map is used (need url here.)
e97f9d6e 856
9c106321 857=item *
e97f9d6e 858
9c106321
TC
859addi - The original code for generating the color map (Addi's code) is
860used.
e97f9d6e 861
9c106321 862=item *
9d1c4956 863
9c106321 864mediancut - Uses a mediancut algorithm, faster than 'addi', but not as good a
9d1c4956
TC
865result.
866
9c106321
TC
867=item *
868
869mono, monochrome - a fixed black and white palette, suitable for
870producing bi-level images (eg. facsimile)
871
e97f9d6e
AMH
872=back
873
874Other methods may be added in the future.
875
876=item colors
877
878A arrayref containing Imager::Color objects, which represents the
879starting set of colors to use in translating the images. webmap will
880ignore this. The final colors used are copied back into this array
881(which is expanded if necessary.)
882
883=item max_colors
884
885The maximum number of colors to use in the image.
886
887=item translate
888
889The method used to translate the RGB values in the source image into
890the colors selected by make_colors. Note that make_colors is ignored
891whene translate is 'giflib'.
892
893Possible values are:
894
895=over
896
897=item giflib
898
899The giflib native quantization function is used.
900
901=item closest
902
903The closest color available is used.
904
905=item perturb
906
907The pixel color is modified by perturb, and the closest color is chosen.
908
909=item errdiff
910
911An error diffusion dither is performed.
912
913=back
914
915It's possible other transate values will be added.
916
917=item errdiff
918
919The type of error diffusion dither to perform. These values (except
920for custom) can also be used in tr_errdif.
921
922=over
923
924=item floyd
925
926Floyd-Steinberg dither
927
928=item jarvis
929
930Jarvis, Judice and Ninke dither
931
932=item stucki
933
934Stucki dither
935
936=item custom
937
938Custom. If you use this you must also set errdiff_width,
939errdiff_height and errdiff_map.
940
941=back
942
943=item errdiff_width
944
945=item errdiff_height
946
947=item errdiff_orig
948
949=item errdiff_map
950
951When translate is 'errdiff' and errdiff is 'custom' these define a
952custom error diffusion map. errdiff_width and errdiff_height define
953the size of the map in the arrayref in errdiff_map. errdiff_orig is
954an integer which indicates the current pixel position in the top row
955of the map.
956
957=item perturb
958
959When translate is 'perturb' this is the magnitude of the random bias
960applied to each channel of the pixel before it is looked up in the
961color table.
962
963=back
964
d5556805
TC
965=head1 INITIALIZATION
966
967This documents the Imager initialization function, which you will
968almost never need to call.
969
970=over
971
972=item init
973
974This is a function, not a method.
975
976This function is a mess, it can take the following named parameters:
977
978=over
979
980=item *
981
982log - name of a log file to log Imager's actions to. Not all actions
983are logged, but the debugging memory allocator does log allocations
984here. Ignored if Imager has been built without logging support.
985
986=item *
987
988loglevel - the maximum level of message to log. Default: 1.
989
990=item *
991
992warn_obsolete - if this is non-zero then Imager will warn when you
993attempt to use obsoleted parameters or functionality. This currently
994only includes the old gif output options instead of tags.
995
996=item *
997
998t1log - if non-zero then T1lib will be configured to produce a log
999file. This will fail if there are any existing T1lib font objects.
1000
1001=back
1002
1003Example:
1004
1005 Imager::init(log => 'trace.log', loglevel => 9);
1006
1007=back
1008
4b3408a5
TC
1009=head1 REVISION
1010
1011$Revision$
1012
1013=head1 AUTHORS
1014
1015Tony Cook, Arnar M. Hrafnkelsson
1016
1017=head1 SEE ALSO
1018
1019Imager(3), Imager::Files(3), Imager::Draw(3),
1020Imager::Color(3), Imager::Fill(3), Imager::Font(3),
1021Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
1022Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)
bac4fcee 1023
9d1c4956 1024=cut