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::Tutorial - a brief introduction to Imager.
59
60       ·   Imager::Cookbook - how to do various things with Imager.
61
62       ·   Imager::ImageTypes - Basics of constructing image objects with
63           "new()": Direct type/virtual images, RGB(A)/paletted images,
64           8/16/double bits/channel, color maps, channel masks, image tags,
65           color quantization.  Also discusses basic image information
66           methods.
67
68       ·   Imager::Files - IO interaction, reading/writing images, format
69           specific tags.
70
71       ·   Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs,
72           flood fill.
73
74       ·   Imager::Color - Color specification.
75
76       ·   Imager::Fill - Fill pattern specification.
77
78       ·   Imager::Font - General font rendering, bounding boxes and font
79           metrics.
80
81       ·   Imager::Transformations - Copying, scaling, cropping, flipping,
82           blending, pasting, convert and map.
83
84       ·   Imager::Engines - Programmable transformations through
85           "transform()", "transform2()" and "matrix_transform()".
86
87       ·   Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and
88           filter plug-ins.
89
90       ·   Imager::Expr - Expressions for evaluation engine used by
91           transform2().
92
93       ·   Imager::Matrix2d - Helper class for affine transformations.
94
95       ·   Imager::Fountain - Helper for making gradient profiles.
96
97       ·   Imager::API - using Imager's C API
98
99       ·   Imager::APIRef - API function reference
100
101       ·   Imager::Inline - using Imager's C API from Inline::C
102
103       ·   Imager::ExtUtils - tools to get access to Imager's C API.
104
105   Basic Overview
106       An Image object is created with "$img = Imager->new()".  Examples:
107
108         $img=Imager->new();                         # create empty image
109         $img->read(file=>'lena.png',type=>'png') or # read image from file
110            die $img->errstr();                      # give an explanation
111                                                     # if something failed
112
113       or if you want to create an empty image:
114
115         $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
116
117       This example creates a completely black image of width 400 and height
118       300 and 4 channels.
119

ERROR HANDLING

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

METHOD INDEX

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

CONCEPT INDEX

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

THREADS

540       Imager doesn't support perl threads.
541
542       Imager has limited code to prevent double frees if you create images,
543       colors etc, and then create a thread, but has no code to prevent two
544       threads entering Imager's error handling code, and none is likely to be
545       added.
546

SUPPORT

548       The best place to get help with Imager is the mailing list.
549
550       To subscribe send a message with "subscribe" in the body to:
551
552          imager-devel+request@molar.is
553
554       or use the form at:
555
556           http://www.molar.is/en/lists/imager-devel/
557           <http://www.molar.is/en/lists/imager-devel/>
558
559       where you can also find the mailing list archive.
560
561       You can report bugs by pointing your browser at:
562
563           <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager>
564
565       or by sending an email to:
566
567           bug-Imager@rt.cpan.org
568
569       Please remember to include the versions of Imager, perl, supporting
570       libraries, and any relevant code.  If you have specific images that
571       cause the problems, please include those too.
572
573       If you don't want to publish your email address on a mailing list you
574       can use CPAN::Forum:
575
576         http://www.cpanforum.com/dist/Imager
577
578       You will need to register to post.
579

CONTRIBUTING TO IMAGER

581   Feedback
582       I like feedback.
583
584       If you like or dislike Imager, you can add a public review of Imager at
585       CPAN Ratings:
586
587         http://cpanratings.perl.org/dist/Imager
588
589       This requires a Bitcard account (http://www.bitcard.org).
590
591       You can also send email to the maintainer below.
592
593       If you send me a bug report via email, it will be copied to Request
594       Tracker.
595
596   Patches
597       I accept patches, preferably against the main branch in subversion.
598       You should include an explanation of the reason for why the patch is
599       needed or useful.
600
601       Your patch should include regression tests where possible, otherwise it
602       will be delayed until I get a chance to write them.
603

AUTHOR

605       Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.
606
607       Arnar M. Hrafnkelsson is the original author of Imager.
608
609       Many others have contributed to Imager, please see the "README" for a
610       complete list.
611

LICENSE

613       Imager is licensed under the same terms as perl itself.
614
615       A test font, FT2/fontfiles/MMOne.pfb, contains a Postscript operator
616       definition copyrighted by Adobe.  See adobe.txt in the source for
617       license information.
618