1Imager(3) User Contributed Perl Documentation Imager(3)
2
3
4
6 Imager - Perl extension for Generating 24 bit Images
7
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
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
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
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
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
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
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
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
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
667 perl(1), Imager::ImageTypes(3), Imager::Files(3), Imager::Draw(3),
668 Imager::Color(3), Imager::Fill(3), Imager::Font(3),
669 Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
670 Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)
671
672 <http://imager.perl.org/>
673
674 Affix::Infix2Postfix(3), Parse::RecDescent(3)
675
676 Other perl imaging modules include:
677
678 GD(3), Image::Magick(3), Graphics::Magick
679 <http://www.graphicsmagick.org/perl.html>(3), Prima::Image, IPA.
680
681 For manipulating image metadata see Image::ExifTool.
682
683 If you're trying to use Imager for array processing, you should
684 probably using PDL.
685
686
687
688perl v5.30.1 2020-01-30 Imager(3)