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

CONCEPT INDEX

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

SUPPORT

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

CONTRIBUTING TO IMAGER

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

AUTHOR

651       Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.
652
653       Arnar M. Hrafnkelsson is the original author of Imager.
654
655       Many others have contributed to Imager, please see the "README" for a
656       complete list.
657

LICENSE

659       Imager is licensed under the same terms as perl itself.
660
661       A test font, generated by the Debian packaged Fontforge,
662       FT2/fontfiles/MMOne.pfb, contains a Postscript operator definition
663       copyrighted by Adobe.  See adobe.txt in the source for license
664       information.
665