Imager(3pm)

1Imager(3)             User Contributed Perl Documentation            Imager(3)
2
3
4

NAME

6       Imager - Perl extension for Generating 24 bit Images
7

SYNOPSIS

9         # Thumbnail example
10
11         #!/usr/bin/perl -w
12         use strict;
13         use Imager;
14
15         die "Usage: thumbmake.pl filename\n" if !-f $ARGV[0];
16         my $file = shift;
17
18         my $format;
19
20         # see Imager::Files for information on the read() method
21         my $img = Imager->new(file=>$file)
22           or die Imager->errstr();
23
24         $file =~ s/\.[^.]*$//;
25
26         # Create smaller version
27         # documented in Imager::Transformations
28         my $thumb = $img->scale(scalefactor=>.3);
29
30         # Autostretch individual channels
31         $thumb->filter(type=>'autolevels');
32
33         # try to save in one of these formats
34         SAVE:
35
36         for $format ( qw( png gif jpeg tiff ppm ) ) {
37           # Check if given format is supported
38           if ($Imager::formats{$format}) {
39             $file.="_low.$format";
40             print "Storing image as: $file\n";
41             # documented in Imager::Files
42             $thumb->write(file=>$file) or
43               die $thumb->errstr;
44             last SAVE;
45           }
46         }
47

DESCRIPTION

49       Imager is a module for creating and altering images.  It can read and
50       write various image formats, draw primitive shapes like lines,and
51       polygons, blend multiple images together in various ways, scale, crop,
52       render text and more.
53
54   Overview of documentation
55       ·   Imager - This document - Synopsis, Example, Table of Contents and
56           Overview.
57
58       ·   Imager::Install - installation notes for Imager.
59
60       ·   Imager::Tutorial - a brief introduction to Imager.
61
62       ·   Imager::Cookbook - how to do various things with Imager.
63
64       ·   Imager::ImageTypes - Basics of constructing image objects with
65           "new()": Direct type/virtual images, RGB(A)/paletted images,
66           8/16/double bits/channel, color maps, channel masks, image tags,
67           color quantization.  Also discusses basic image information
68           methods.
69
70       ·   Imager::Files - IO interaction, reading/writing images, format
71           specific tags.
72
73       ·   Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs,
74           flood fill.
75
76       ·   Imager::Color - Color specification.
77
78       ·   Imager::Fill - Fill pattern specification.
79
80       ·   Imager::Font - General font rendering, bounding boxes and font
81           metrics.
82
83       ·   Imager::Transformations - Copying, scaling, cropping, flipping,
84           blending, pasting, convert and map.
85
86       ·   Imager::Engines - Programmable transformations through
87           "transform()", "transform2()" and "matrix_transform()".
88
89       ·   Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and
90           filter plug-ins.
91
92       ·   Imager::Expr - Expressions for evaluation engine used by
93           transform2().
94
95       ·   Imager::Matrix2d - Helper class for affine transformations.
96
97       ·   Imager::Fountain - Helper for making gradient profiles.
98
99       ·   Imager::IO - Imager I/O abstraction.
100
101       ·   Imager::API - using Imager's C API
102
103       ·   Imager::APIRef - API function reference
104
105       ·   Imager::Inline - using Imager's C API from Inline::C
106
107       ·   Imager::ExtUtils - tools to get access to Imager's C API.
108
109       ·   Imager::Security - brief security notes.
110
111       ·   Imager::Threads - brief information on working with threads.
112
113   Basic Overview
114       An Image object is created with "$img = Imager->new()".  Examples:
115
116         $img=Imager->new();                         # create empty image
117         $img->read(file=>'lena.png',type=>'png') or # read image from file
118            die $img->errstr();                      # give an explanation
119                                                     # if something failed
120
121       or if you want to create an empty image:
122
123         $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
124
125       This example creates a completely black image of width 400 and height
126       300 and 4 channels.
127

ERROR HANDLING

129       In general a method will return false when it fails, if it does use the
130       "errstr()" method to find out why:
131
132       errstr()
133           Returns the last error message in that context.
134
135           If the last error you received was from calling an object method,
136           such as read, call errstr() as an object method to find out why:
137
138             my $image = Imager->new;
139             $image->read(file => 'somefile.gif')
140                or die $image->errstr;
141
142           If it was a class method then call errstr() as a class method:
143
144             my @imgs = Imager->read_multi(file => 'somefile.gif')
145               or die Imager->errstr;
146
147           Note that in some cases object methods are implemented in terms of
148           class methods so a failing object method may set both.
149
150       The "Imager->new" method is described in detail in Imager::ImageTypes.
151

METHOD INDEX

153       Where to find information on methods for Imager class objects.
154
155       addcolors() - "addcolors()" in Imager::ImageTypes - add colors to a
156       paletted image
157
158       addtag() -  "addtag()" in Imager::ImageTypes - add image tags
159
160       add_type_extensions() - "add_type_extensions($type, $ext, ...)" in
161       Imager::Files - add extensions for new image file types.
162
163       align_string() - "align_string()" in Imager::Draw - draw text aligned
164       on a point
165
166       alphachannel() - "alphachannel()" in Imager::ImageTypes - return the
167       channel index of the alpha channel (if any).
168
169       arc() - "arc()" in Imager::Draw - draw a filled arc
170
171       bits() - "bits()" in Imager::ImageTypes - number of bits per sample for
172       the image
173
174       box() - "box()" in Imager::Draw - draw a filled or outline box.
175
176       check_file_limits() - "check_file_limits()" in Imager::Files
177
178       circle() - "circle()" in Imager::Draw - draw a filled circle
179
180       close_log() - "close_log()" in Imager::ImageTypes - close the Imager
181       debugging log.
182
183       colorchannels() - "colorchannels()" in Imager::ImageTypes - the number
184       of channels used for color.
185
186       colorcount() - "colorcount()" in Imager::ImageTypes - the number of
187       colors in an image's palette (paletted images only)
188
189       colormodel() - "colorcount()" in Imager::ImageTypes - how color is
190       represented.
191
192       combine() - "combine()" in Imager::Transformations - combine channels
193       from one or more images.
194
195       combines() - "combines()" in Imager::Draw - return a list of the
196       different combine type keywords
197
198       compose() - "compose()" in Imager::Transformations - compose one image
199       over another.
200
201       convert() - "convert()" in Imager::Transformations - transform the
202       color space
203
204       copy() - "copy()" in Imager::Transformations - make a duplicate of an
205       image
206
207       crop() - "crop()" in Imager::Transformations - extract part of an image
208
209       def_guess_type() - "def_guess_type()" in Imager::Files - default
210       function used to guess the output file format based on the output file
211       name
212
213       deltag() -  "deltag()" in Imager::ImageTypes - delete image tags
214
215       difference() - "difference()" in Imager::Filters - produce a difference
216       images from two input images.
217
218       errstr() - "errstr()" - the error from the last failed operation.
219
220       filter() - "filter()" in Imager::Filters - image filtering
221
222       findcolor() - "findcolor()" in Imager::ImageTypes - search the image
223       palette, if it has one
224
225       flip() - "flip()" in Imager::Transformations - flip an image,
226       vertically, horizontally
227
228       flood_fill() - "flood_fill()" in Imager::Draw - fill an enclosed or
229       same color area
230
231       getchannels() - "getchannels()" in Imager::ImageTypes - the number of
232       samples per pixel for an image
233
234       getcolorcount() - "getcolorcount()" in Imager::ImageTypes - the number
235       of different colors used by an image (works for direct color images)
236
237       getcolors() - "getcolors()" in Imager::ImageTypes - get colors from the
238       image palette, if it has one
239
240       getcolorusage() - "getcolorusage()" in Imager::ImageTypes
241
242       getcolorusagehash() - "getcolorusagehash()" in Imager::ImageTypes
243
244       get_file_limits() - "get_file_limits()" in Imager::Files
245
246       getheight() - "getheight()" in Imager::ImageTypes - height of the image
247       in pixels
248
249       getmask() - "getmask()" in Imager::ImageTypes - write mask for the
250       image
251
252       getpixel() - "getpixel()" in Imager::Draw - retrieve one or more pixel
253       colors
254
255       getsamples() - "getsamples()" in Imager::Draw - retrieve samples from a
256       row or partial row of pixels.
257
258       getscanline() - "getscanline()" in Imager::Draw - retrieve colors for a
259       row or partial row of pixels.
260
261       getwidth() - "getwidth()" in Imager::ImageTypes - width of the image in
262       pixels.
263
264       img_set() - "img_set()" in Imager::ImageTypes - re-use an Imager object
265       for a new image.
266
267       init() - "init()" in Imager::ImageTypes
268
269       is_bilevel() - "is_bilevel()" in Imager::ImageTypes - returns whether
270       image write functions should write the image in their bilevel (blank
271       and white, no gray levels) format
272
273       is_logging() "is_logging()" in Imager::ImageTypes - test if the debug
274       log is active.
275
276       line() - "line()" in Imager::Draw - draw an interval
277
278       load_plugin() - "load_plugin()" in Imager::Filters
279
280       log() - "log()" in Imager::ImageTypes - send a message to the debugging
281       log.
282
283       make_palette() - "make_palette()" in Imager::ImageTypes - produce a
284       color palette from one or more input images.
285
286       map() - "map()" in Imager::Transformations - remap color channel values
287
288       masked() -  "masked()" in Imager::ImageTypes - make a masked image
289
290       matrix_transform() - "matrix_transform()" in Imager::Engines
291
292       maxcolors() - "maxcolors()" in Imager::ImageTypes
293
294       NC() - "NC()" in Imager::Handy
295
296       NCF() - "NCF()" in Imager::Handy
297
298       new() - "new()" in Imager::ImageTypes
299
300       newcolor() - "newcolor()" in Imager::Handy
301
302       newcolour() - "newcolour()" in Imager::Handy
303
304       newfont() - "newfont()" in Imager::Handy
305
306       NF() - "NF()" in Imager::Handy
307
308       open() - "read()" in Imager::Files - an alias for read()
309
310       open_log() - "open_log()" in Imager::ImageTypes - open the debug log.
311
312       parseiptc() - "parseiptc()" in Imager::Files - parse IPTC data from a
313       JPEG image
314
315       paste() - "paste()" in Imager::Transformations - draw an image onto an
316       image
317
318       polygon() - "polygon()" in Imager::Draw
319
320       polyline() - "polyline()" in Imager::Draw
321
322       polypolygon() - "polypolygon()" in Imager::Draw
323
324       preload() - "preload()" in Imager::Files
325
326       read() - "read()" in Imager::Files - read a single image from an image
327       file
328
329       read_multi() - "read_multi()" in Imager::Files - read multiple images
330       from an image file
331
332       read_types() - "read_types()" in Imager::Files - list image types
333       Imager can read.
334
335       register_filter() - "register_filter()" in Imager::Filters
336
337       register_reader() - "register_reader()" in Imager::Files
338
339       register_writer() - "register_writer()" in Imager::Files
340
341       rotate() - "rotate()" in Imager::Transformations
342
343       rubthrough() - "rubthrough()" in Imager::Transformations - draw an
344       image onto an image and use the alpha channel
345
346       scale() - "scale()" in Imager::Transformations
347
348       scale_calculate() - "scale_calculate()" in Imager::Transformations
349
350       scaleX() - "scaleX()" in Imager::Transformations
351
352       scaleY() - "scaleY()" in Imager::Transformations
353
354       setcolors() - "setcolors()" in Imager::ImageTypes - set palette colors
355       in a paletted image
356
357       set_file_limits() - "set_file_limits()" in Imager::Files
358
359       setmask() - "setmask()" in Imager::ImageTypes
360
361       setpixel() - "setpixel()" in Imager::Draw
362
363       setsamples() - "setsamples()" in Imager::Draw
364
365       setscanline() - "setscanline()" in Imager::Draw
366
367       settag() - "settag()" in Imager::ImageTypes
368
369       string() - "string()" in Imager::Draw - draw text on an image
370
371       tags() -  "tags()" in Imager::ImageTypes - fetch image tags
372
373       to_paletted() -  "to_paletted()" in Imager::ImageTypes
374
375       to_rgb16() - "to_rgb16()" in Imager::ImageTypes
376
377       to_rgb8() - "to_rgb8()" in Imager::ImageTypes
378
379       to_rgb_double() - "to_rgb_double()" in Imager::ImageTypes - convert to
380       double per sample image.
381
382       transform() - "transform()" in Imager::Engines
383
384       transform2() - "transform2()" in Imager::Engines
385
386       type() -  "type()" in Imager::ImageTypes - type of image (direct vs
387       paletted)
388
389       unload_plugin() - "unload_plugin()" in Imager::Filters
390
391       virtual() - "virtual()" in Imager::ImageTypes - whether the image has
392       it's own data
393
394       write() - "write()" in Imager::Files - write an image to a file
395
396       write_multi() - "write_multi()" in Imager::Files - write multiple image
397       to an image file.
398
399       write_types() - "read_types()" in Imager::Files - list image types
400       Imager can write.
401

CONCEPT INDEX

403       animated GIF - "Writing an animated GIF" in Imager::Files
404
405       aspect ratio - "i_xres", "i_yres", "i_aspect_only" in "Common Tags" in
406       Imager::ImageTypes.
407
408       blend - alpha blending one image onto another "rubthrough()" in
409       Imager::Transformations
410
411       blur - "gaussian" in Imager::Filters, "conv" in Imager::Filters
412
413       boxes, drawing - "box()" in Imager::Draw
414
415       changes between image - "Image Difference" in Imager::Filters
416
417       channels, combine into one image - "combine()" in
418       Imager::Transformations
419
420       color - Imager::Color
421
422       color names - Imager::Color, Imager::Color::Table
423
424       combine modes - "Combine Types" in Imager::Draw
425
426       compare images - "Image Difference" in Imager::Filters
427
428       contrast - "contrast" in Imager::Filters, "autolevels" in
429       Imager::Filters
430
431       convolution - "conv" in Imager::Filters
432
433       cropping - "crop()" in Imager::Transformations
434
435       CUR files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
436       Cursor)" in Imager::Files
437
438       "diff" images - "Image Difference" in Imager::Filters
439
440       dpi - "i_xres", "i_yres" in "Common Tags" in Imager::ImageTypes, "Image
441       spatial resolution" in Imager::Cookbook
442
443       drawing boxes - "box()" in Imager::Draw
444
445       drawing lines - "line()" in Imager::Draw
446
447       drawing text - "string()" in Imager::Draw, "align_string()" in
448       Imager::Draw
449
450       error message - "ERROR HANDLING"
451
452       files, font - Imager::Font
453
454       files, image - Imager::Files
455
456       filling, types of fill - Imager::Fill
457
458       filling, boxes - "box()" in Imager::Draw
459
460       filling, flood fill - "flood_fill()" in Imager::Draw
461
462       flood fill - "flood_fill()" in Imager::Draw
463
464       fonts - Imager::Font
465
466       fonts, drawing with - "string()" in Imager::Draw, "align_string()" in
467       Imager::Draw, Imager::Font::Wrap
468
469       fonts, metrics - "bounding_box()" in Imager::Font, Imager::Font::BBox
470
471       fonts, multiple master - "MULTIPLE MASTER FONTS" in Imager::Font
472
473       fountain fill - "Fountain fills" in Imager::Fill, "fountain" in
474       Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
475
476       GIF files - "GIF" in Imager::Files
477
478       GIF files, animated - "Writing an animated GIF" in Imager::Files
479
480       gradient fill - "Fountain fills" in Imager::Fill, "fountain" in
481       Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
482
483       gray scale, convert image to - "convert()" in Imager::Transformations
484
485       gaussian blur - "gaussian" in Imager::Filters
486
487       hatch fills - "Hatched fills" in Imager::Fill
488
489       ICO files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
490       Cursor)" in Imager::Files
491
492       invert image - "hardinvert" in Imager::Filters, "hardinvertall" in
493       Imager::Filters
494
495       JPEG - "JPEG" in Imager::Files
496
497       limiting image sizes - "Limiting the sizes of images you read" in
498       Imager::Files
499
500       lines, drawing - "line()" in Imager::Draw
501
502       matrix - Imager::Matrix2d, "Matrix Transformations" in Imager::Engines,
503       "transform()" in Imager::Font
504
505       metadata, image - "Tags" in Imager::ImageTypes, Image::ExifTool
506
507       mosaic - "mosaic" in Imager::Filters
508
509       noise, filter - "noise" in Imager::Filters
510
511       noise, rendered - "turbnoise" in Imager::Filters, "radnoise" in
512       Imager::Filters
513
514       paste - "paste()" in Imager::Transformations, "rubthrough()" in
515       Imager::Transformations
516
517       pseudo-color image - "to_paletted()" in Imager::ImageTypes, "new()" in
518       Imager::ImageTypes
519
520       posterize - "postlevels" in Imager::Filters
521
522       PNG files - Imager::Files, "PNG" in Imager::Files
523
524       PNM - "PNM (Portable aNy Map)" in Imager::Files
525
526       rectangles, drawing - "box()" in Imager::Draw
527
528       resizing an image - "scale()" in Imager::Transformations, "crop()" in
529       Imager::Transformations
530
531       RGB (SGI) files - "SGI (RGB, BW)" in Imager::Files
532
533       saving an image - Imager::Files
534
535       scaling - "scale()" in Imager::Transformations
536
537       security - Imager::Security
538
539       SGI files - "SGI (RGB, BW)" in Imager::Files
540
541       sharpen - "unsharpmask" in Imager::Filters, "conv" in Imager::Filters
542
543       size, image - "getwidth()" in Imager::ImageTypes, "getheight()" in
544       Imager::ImageTypes
545
546       size, text - "bounding_box()" in Imager::Font
547
548       tags, image metadata - "Tags" in Imager::ImageTypes
549
550       text, drawing - "string()" in Imager::Draw, "align_string()" in
551       Imager::Draw, Imager::Font::Wrap
552
553       text, wrapping text in an area - Imager::Font::Wrap
554
555       text, measuring - "bounding_box()" in Imager::Font, Imager::Font::BBox
556
557       threads - Imager::Threads
558
559       tiles, color - "mosaic" in Imager::Filters
560
561       transparent images - Imager::ImageTypes, "Transparent PNG" in
562       Imager::Cookbook
563
564       unsharp mask - "unsharpmask" in Imager::Filters
565
566       watermark - "watermark" in Imager::Filters
567
568       writing an image to a file - Imager::Files
569

SUPPORT

571       The best place to get help with Imager is the mailing list.
572
573       To subscribe send a message with "subscribe" in the body to:
574
575          imager-devel+request@molar.is
576
577       or use the form at:
578
579           <http://www.molar.is/en/lists/imager-devel/>
580
581       where you can also find the mailing list archive.
582
583       You can report bugs by pointing your browser at:
584
585           <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager>
586
587       or by sending an email to:
588
589           bug-Imager@rt.cpan.org
590
591       Please remember to include the versions of Imager, perl, supporting
592       libraries, and any relevant code.  If you have specific images that
593       cause the problems, please include those too.
594
595       If you don't want to publish your email address on a mailing list you
596       can use CPAN::Forum:
597
598         http://www.cpanforum.com/dist/Imager
599
600       You will need to register to post.
601

CONTRIBUTING TO IMAGER

603   Feedback
604       I like feedback.
605
606       If you like or dislike Imager, you can add a public review of Imager at
607       CPAN Ratings:
608
609         http://cpanratings.perl.org/dist/Imager
610
611       This requires a Bitcard account (http://www.bitcard.org).
612
613       You can also send email to the maintainer below.
614
615       If you send me a bug report via email, it will be copied to Request
616       Tracker.
617
618   Patches
619       I accept patches, preferably against the master branch in git.  Please
620       include an explanation of the reason for why the patch is needed or
621       useful.
622
623       Your patch should include regression tests where possible, otherwise it
624       will be delayed until I get a chance to write them.
625
626       To browse Imager's git repository:
627
628         http://git.imager.perl.org/imager.git
629
630       To clone:
631
632         git clone git://git.imager.perl.org/imager.git
633
634       My preference is that patches are provided in the format produced by
635       "git format-patch", for example, if you made your changes in a branch
636       from master you might do:
637
638         git format-patch -k --stdout master >my-patch.txt
639
640       and then attach that to your bug report, either by adding it as an
641       attachment in your email client, or by using the Request Tracker
642       attachment mechanism.
643

AUTHOR

645       Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.
646
647       Arnar M. Hrafnkelsson is the original author of Imager.
648
649       Many others have contributed to Imager, please see the "README" for a
650       complete list.
651

LICENSE

653       Imager is licensed under the same terms as perl itself.
654
655       A test font, generated by the Debian packaged Fontforge,
656       FT2/fontfiles/MMOne.pfb, contains a Postscript operator definition
657       copyrighted by Adobe.  See adobe.txt in the source for license
658       information.
659