GD::SecurityImage(3pm)

1GD::SecurityImage(3)  User Contributed Perl Documentation GD::SecurityImage(3)
2
3
4

NAME

6       GD::SecurityImage - Security image (captcha) generator.
7

SYNOPSIS

9          use GD::SecurityImage;
10
11          # Create a normal image
12          my $image = GD::SecurityImage->new(width   => 80,
13                                             height  => 30,
14                                             lines   => 10,
15                                             gd_font => 'giant');
16             $image->random($your_random_str);
17             $image->create(normal => 'rect');
18          my($image_data, $mime_type, $random_number) = $image->out;
19
20       or
21
22          # use external ttf font
23          my $image = GD::SecurityImage->new(width    => 100,
24                                             height   => 40,
25                                             lines    => 10,
26                                             font     => "/absolute/path/to/your.ttf",
27                                             scramble => 1);
28             $image->random($your_random_str);
29             $image->create(ttf => 'default');
30             $image->particle;
31          my($image_data, $mime_type, $random_number) = $image->out;
32
33       or you can just say (most of the public methods can be chained)
34
35          my($image, $type, $rnd) = GD::SecurityImage->new->random->create->particle->out;
36
37       to create a security image with the default settings. But that may not
38       be useful. If you "require" the module, you must import it:
39
40          require GD::SecurityImage;
41          GD::SecurityImage->import;
42
43       The module also supports "Image::Magick", but the default interface
44       uses the "GD" module. To enable "Image::Magick" support, you must call
45       the module with the "use_magick" option:
46
47          use GD::SecurityImage use_magick => 1;
48
49       If you "require" the module, you must import it:
50
51          require GD::SecurityImage;
52          GD::SecurityImage->import(use_magick => 1);
53
54       The module does not export anything actually. But "import" loads the
55       necessary sub modules. If you don' t "import", the required modules
56       will not be loaded and probably, you'll "die()".
57

DESCRIPTION

59       This document describes version 1.70 of "GD::SecurityImage" released on
60       "30 April 2009".
61
62       The (so called) "Security Images" are so popular. Most internet
63       software use these in their registration screens to block robot
64       programs (which may register tons of  fake member accounts). Security
65       images are basicaly, graphical CAPTCHAs (Completely Automated Public
66       Turing Test to Tell Computers and Humans Apart). This module gives you
67       a basic interface to create such an image. The final output is the
68       actual graphic data, the mime type of the graphic and the created
69       random string. The module also has some "styles" that are used to
70       create the background (or foreground) of the image.
71
72       If you are an "Authen::Captcha" user, see GD::SecurityImage::AC for
73       migration from "Authen::Captcha" to "GD::SecurityImage".
74
75       This module is just an image generator. Not a captcha handler.  The
76       validation of the generated graphic is left to your programming taste.
77       But there are some captcha handlers for several Perl FrameWorks.  If
78       you are an user of one of these frameworks, see "GD::SecurityImage
79       Implementations" in "SEE ALSO" section for information.
80

COLOR PARAMETERS

82       This module can use both RGB and HEX values as the color parameters.
83       HEX values are recommended, since they are widely used and recognised.
84
85          $color  = '#80C0F0';     # HEX
86          $color2 = [15, 100, 75]; # RGB
87          $i->create($meth, $style, $color, $color2)
88
89          $i->create(ttf => 'box', '#80C0F0', '#0F644B')
90
91       RGB values must be passed as an array reference including the three
92       Red, Green and Blue values.
93
94       Color conversion is transparent to the user. You can use hex values
95       under both "GD" and "Image::Magick". They' ll be automagically
96       converted to RGB if you are under "GD".
97

METHODS

99   new
100       The constructor. "new()" method takes several arguments. These
101       arguments are listed below.
102
103       width
104           The width of the image (in pixels).
105
106       height
107           The height of the image (in pixels).
108
109       ptsize
110           Numerical value. The point size of the ttf character.  Only
111           necessarry if you want to use a ttf font in the image.
112
113       lines
114           The number of lines that you' ll see in the background of the
115           image.  The alignment of lines can be vertical, horizontal or
116           angled or all of them. If you increase this parameter' s value, the
117           image will be more cryptic.
118
119       font
120           The absolute path to your TrueType (.ttf) font file. Be aware that
121           relative font paths are not recognized due to problems in the
122           "libgd" library.
123
124           If you are sure that you've set this parameter to a correct value
125           and you get warnings or you get an empty image, be sure that your
126           path does not include spaces in it. It looks like libgd also have
127           problems with this kind of paths (eg: '/Documents and
128           Settings/user' under Windows).
129
130           Set this parameter if you want to use ttf in your image.
131
132       gd_font
133           If you want to use the default interface, set this paramater. The
134           recognized values are "Small", "Large", "MediumBold", "Tiny",
135           "Giant".  The names are case-insensitive; you can pass lower-cased
136           parameters.
137
138       bgcolor
139           The background color of the image.
140
141       send_ctobg
142           If has a true value, the random security code will be displayed in
143           the background and the lines will pass over it.  (send_ctobg = send
144           code to background)
145
146       frame
147           If has a true value, a frame will be added around the image. This
148           option is enabled by default.
149
150       scramble
151           If set, the characters will be scrambled. If you enable this
152           option, be sure to use a wider image, since the characters will be
153           separated with three spaces.
154
155       angle
156           Sets the angle for scrambled/normal characters. Beware that, if you
157           pass an "angle" parameter, the characters in your random string
158           will have a fixed angle. If you do not set an "angle" parameter,
159           the angle(s) will be random.
160
161           When the scramble option is not enabled, this parameter still
162           controls the angle of the text. But, since the text will be
163           centered inside the image, using this parameter without scramble
164           option will require a taller image. Clipping will occur with
165           smaller height values.
166
167           Unlike the GD interface, "angle" is in "degree"s and can take
168           values between 0 and 360.
169
170       thickness
171           Sets the line drawing width. Can take numerical values.  Default
172           values are 1 for GD and 0.6 for Image:Magick.
173
174       rndmax
175           The minimum length of the random string. Default value is 6.
176
177       rnd_data
178           Default character set used to create the random string is 0..9.
179           But, if you want to use letters also, you can set this paramater.
180           This paramater takes an array reference as the value.
181
182           Not necessary and will not be used if you pass your own random
183           string.
184
185   random
186       Creates the random security string or sets the random string to the
187       value you have passed. If you pass your own random string, be aware
188       that it must be at least six (defined in "rndmax") characters long.
189
190   random_str
191       Returns the random string. Must be called after "random()".
192
193   create
194       This method creates the actual image. It takes four arguments, but none
195       are mandatory.
196
197          $image->create($method, $style, $text_color, $line_color);
198
199       $method can be "normal" or "ttf".
200
201       $style can be one of the following (some of the styles may not work if
202       you are using a really old version of GD):
203
204       default
205           The default style. Draws horizontal, vertical and angular lines.
206
207       rect
208           Draws horizontal and vertical lines
209
210       box Draws two filled rectangles.
211
212           The "lines" option passed to new, controls the size of the inner
213           rectangle for this style. If you increase the "lines", you'll get a
214           smaller internal rectangle. Using smaller values like 5 can be
215           better.
216
217       circle
218           Draws circles.
219
220       ellipse
221           Draws ellipses.
222
223       ec  This is the combination of ellipse and circle styles. Draws both
224           ellipses and circles.
225
226       blank
227           Draws nothing. See "OTHER USES".
228
229       Note: if you have a (too) old version of GD, you may not be able to use
230       some of the styles.
231
232       You can use this code to get all available style names:
233
234          my @styles = grep {s/^style_//} keys %GD::SecurityImage::Styles::;
235
236       The last two arguments ($text_color and $line_color) are the colors
237       used in the image (text and line color -- respectively):
238
239          $image->create($method, $style, [0,0,0], [200,200,200]);
240          $image->create($method, $style, '#000000', '#c8c8c8');
241
242   particle
243       Must be called after create.
244
245       Adds random dots to the image. They'll cover all over the surface.
246       Accepts two parameters; the density (number) of the particles and the
247       maximum number of dots around the main dot.
248
249          $image->particle($density, $maxdots);
250
251       Default value of $density is dependent on your image' s width or height
252       value. The greater value of width and height is taken and multiplied by
253       twenty. So; if your width is 200 and height is 70, $density is "200 *
254       20 = 4000" (unless you pass your own value).  The default value of
255       $density can be too much for smaller images.
256
257       $maxdots defines the maximum number of dots near the default dot.
258       Default value is 1. If you set it to 4, The selected pixel and 3 other
259       pixels near it will be used and colored.
260
261       The color of the particles are the same as the color of your text
262       (defined in create).
263
264   info_text
265       This method must be called after create. If you call it early, you'll
266       die. "info_text" adds an extra text to the generated image. You can
267       also put a strip under the text. The purpose of this method is to
268       display additional information on the image. Copyright informations can
269       be an example for that.
270
271          $image->info_text(
272             x      => 'right',
273             y      => 'up',
274             gd     => 1,
275             strip  => 1,
276             color  => '#000000',
277             scolor => '#FFFFFF',
278             text   => 'Generated by GD::SecurityImage',
279          );
280
281       Options:
282
283       x   Controls the horizontal location of the information text. Can be
284           either "left" or "right".
285
286       y   Controls the vertical location of the information text. Can be
287           either "up" or "down".
288
289       strip
290           If has a true value, a strip will be added to the background of the
291           information text.
292
293       gd  This option can only be used under "GD". Has no effect under
294           Image::Magick. If has a true value, the standard GD font "Tiny"
295           will be used for the information text.
296
297           If this option is not present or has a false value, the TTF font
298           parameter passed to "new" will be used instead.
299
300       ptsize
301           The ptsize value of the information text to be used with the TTF
302           font.  TTF font paramter can not be set with "info_text()". The
303           value passed to "new()" will be used instead.
304
305       color
306           The color of the information text.
307
308       scolor
309           The color of the strip.
310
311       text
312           This parameter controls the displayed text. If you want to display
313           long texts, be sure to adjust the image, or clipping will occur.
314
315   out
316       This method finally returns the created image, the mime type of the
317       image and the random number(s) generated. Older versions of GD only
318       support "gif" type, while new versions support "jpeg" and "png"
319       (update: beginning with v2.15, GD resumed gif support).
320
321       The returned mime type is "png" or "gif" or "jpeg" for "GD" and "gif"
322       for "Image::Magick" (if you do not "force" some other format).
323
324       "out" method accepts arguments:
325
326          @data = $image->out(%args);
327
328       force
329           You can set the output format with the "force" parameter:
330
331              @data = $image->out(force => 'png');
332
333           If "png" is supported by the interface (via "GD" or
334           "Image::Magick"); you'll get a png image, if the interface does not
335           support this format, "out()" method will use it's default
336           configuration.
337
338       compress
339           And with the "compress" parameter, you can define the compression
340           for "png" and quality for "jpeg":
341
342              @data = $image->out(force => 'png' , compress => 1);
343              @data = $image->out(force => 'jpeg', compress => 100);
344
345           When you use "compress" with "png" format, the value of "compress"
346           is ignored and it is only checked if it has a true value. With
347           "png" the compression will always be 9 (maximum compression). eg:
348
349              @data = $image->out(force => 'png' , compress => 1);
350              @data = $image->out(force => 'png' , compress => 3);
351              @data = $image->out(force => 'png' , compress => 5);
352              @data = $image->out(force => 'png' , compress => 1500);
353
354           All will default to 9. But this will disable compression:
355
356              @data = $image->out(force => 'png' , compress => 0);
357
358           But the behaviour changes if the format is "jpeg"; the value of
359           "compress" will be used for "jpeg" quality; which is in the range
360           1..100.
361
362           Compression and quality operations are disabled by default.
363
364   raw
365       Depending on your usage of the module; returns the raw "GD::Image"
366       object:
367
368          my $gd = $image->raw;
369          print $gd->png;
370
371       or the raw "Image::Magick" object:
372
373          my $magick = $image->raw;
374          $magick->Write("gif:-");
375
376       Can be usefull, if you want to modify the graphic yourself. If you want
377       to get an image type see the "force" option in "out".
378
379   gdbox_empty
380       See "path bug" in "GD bug" for usage and other information on this
381       method.
382
383   add_strip
384   cconvert
385   gdf
386   h2r
387   is_hex
388   r2h
389   random_angle

UTILITY METHODS

391   backends
392       Returns a list of available GD::SecurityImage back-ends.
393
394          my @be = GD::SecurityImage->backends;
395
396       or
397
398          my @be = $image->backends;
399
400       If called in a void context, prints a verbose list of available
401       GD::SecurityImage back-ends:
402
403          Available back-ends in GD::SecurityImage v1.55 are:
404                  GD
405                  Magick
406
407          Search directories:
408                     /some/@INC/dir/containing/GDSI
409
410       you can see the output with this command:
411
412          perl -MGD::SecurityImage -e 'GD::SecurityImage->backends'
413
414       or under windows:
415
416          perl -MGD::SecurityImage -e "GD::SecurityImage->backends"
417

EXAMPLES

419       See the tests in the distribution. Also see the demo program
420       "eg/demo.pl" for an "Apache::Session" implementation of
421       "GD::SecurityImage".
422
423       Download the distribution from a CPAN mirror near you, if you don't
424       have the files.
425
426   OTHER USES
427       "GD::SecurityImage" drawing capabilities can also be used for counter
428       image generation or displaying arbitrary messages:
429
430          use CGI qw(header);
431          use GD::SecurityImage 1.64; # we need the "blank" style
432
433          my $font  = "StayPuft.ttf";
434          my $rnd   = "10.257"; # counter data
435
436          my $image = GD::SecurityImage->new(
437             width  =>   140,
438             height =>    75,
439             ptsize =>    30,
440             rndmax =>     1, # keeping this low helps to display short strings
441             frame  =>     0, # disable borders
442             font   => $font,
443          );
444
445          $image->random( $rnd );
446          # use the blank style, so that nothing will be drawn
447          # to distort the image.
448          $image->create( ttf => 'blank', '#CC8A00' );
449          $image->info_text(
450             text   => 'You are visitor number',
451             ptsize => 10,
452             strip  =>  0,
453             color  => '#0094CC',
454          );
455          $image->info_text(
456             text   => '( c ) 2 0 0 7   m y s i t e',
457             ptsize => 10,
458             strip  =>  0,
459             color  => '#d7d7d7',
460             y      => 'down',
461          );
462
463          my($data, $mime, $random) = $image->out;
464
465          binmode STDOUT;
466          print header -type => "image/$mime";
467          print $data;
468

ERROR HANDLING

470       "die" is called in some methods if something fails. You may need to
471       "eval" your code to catch exceptions.
472

TIPS

474       If you look at the demo program (not just look at it, try to run it)
475       you'll see that the random code changes after every request (successful
476       or not). If you do not change the random code after a failed request
477       and display the random code inside HTML (like "Wrong! It must be
478       <random>"), then you are doing a logical mistake, since the user (or
479       robot) can now copy & paste the random code into your validator without
480       looking at the security image and will pass the test. Just don't do
481       that. Random code must change after every validation.
482
483       If you want to be a little more strict, you can also add a timeout key
484       to the session (this feature currently does not exits in the demo) and
485       expire the related random code after the timeout. Since robots can call
486       the image generator directly (without requiring the HTML form), they
487       can examine the image for a while without changing it. A timeout
488       implemetation may prevent this.
489

BUGS

491       See the "SUPPORT" section if you have a bug or request to report.
492
493   Image::Magick bug
494       There is a bug in PerlMagick' s "QueryFontMetrics()" method.
495       ImageMagick versions smaller than 6.0.4 is affected. Below text is from
496       the ImageMagick 6.0.4 Changelog:
497       <http://www.imagemagick.org/www/Changelog.html>.
498
499       "2004-05-06 PerlMagick's "QueryFontMetrics()" incorrectly reports
500       `unrecognized attribute'` for the `font' attribute."
501
502       Please upgrade to ImageMagick 6.0.4 or any newer version, if your
503       ImageMagick version is smaller than 6.0.4 and you want to use
504       Image::Magick as the backend for GD::SecurityImage.
505
506   GD bug
507       path bug
508
509       libgd and GD.pm don't like relative paths and paths that have spaces in
510       them. If you pass a font path that is not an exact path or a path that
511       have a space in it, you may get an empty image.
512
513       To check if the module failed to find the ttf font (when using "GD"), a
514       new method added: "gdbox_empty()". It must be called after "create()":
515
516          $image->create;
517          die "Error loading ttf font for GD: $@" if $image->gdbox_empty;
518
519       "gdbox_empty()" always returns false, if you are using "Image::Magick".
520

COMMON ERRORS

522   Wrong GD installation
523       I got some error reports saying that GD::SecurityImage dies with this
524       error:
525
526          Can't locate object method "new" via package "GD::Image"
527          (perhaps you forgot to load "GD::Image"?) at ...
528
529       This is due to a wrong installation of the GD module. GD includes "XS"
530       code and it needs to be compiled. You can't just copy/paste the GD.pm
531       and expect it to work. It will not.  If you are under Windows and don't
532       have a C compiler, you have to add new repositories to install GD,
533       since ActiveState' s own repositories don't include GD. Randy Kobes and
534       J-L Morel have ppm repositories for both 5.6.x and 5.8.x and they both
535       have GD:
536
537          http://www.bribes.org/perl/ppmdir.html
538          http://theoryx5.uwinnipeg.ca/
539
540       bribes.org also has a GD::SecurityImage ppd, so you can just install
541       GD::SecurityImage from that repository.
542
543   libgd errors
544       There are some issues related to wrong/incomplete compiling of libgd
545       and old/new version conflicts.
546
547       libgd without TTF support
548
549       If your libgd is compiled without TTF support, you'll get an empty
550       image. The lines will be drawn, but there will be no text. You can
551       check it with "gdbox_empty" method.
552
553       GIF - Old libgd or libgd without GIF support enabled
554
555       If your GD has a "gif" method, but you get empty images with "gif()"
556       method, you have to update your libgd or compile it with GIF enabled.
557
558       You can test if "gif" is working from the command line:
559
560          perl -MGD -e '$_=GD::Image->new;$_->colorAllocate(0,0,0);print$_->gif'
561
562       or under windows:
563
564          perl -MGD -e "$_=GD::Image->new;$_->colorAllocate(0,0,0);print$_->gif"
565
566       Conclusions:
567
568       ·   If it dies, your GD is very old.
569
570       ·   If it prints nothing, your libgd was compiled without GIF enabled
571           (upgrade or re-compile).
572
573       ·   If it prints out a junk that starts with 'GIF87a', everything is
574           OK.
575

CAVEAT EMPTOR

577       ·   Using the default library "GD" is a better choice. Since it is
578           faster and does not use that much memory, while "Image::Magick" is
579           slower and uses more memory.
580
581       ·   The internal random code generator is used only for demonstration
582           purposes for this module. It may not be effective. You must supply
583           your own random code and use this module to display it.
584
585       ·   [GD] png compression
586
587           Support for compression level argument to png() added in v2.07. If
588           your GD version is smaller than this, compress option to "out()"
589           will be silently ignored.
590
591       ·   [GD] setThickness
592
593           setThickness implemented in GD v2.07. If your GD version is smaller
594           than that and you set thickness option, nothing will happen.
595
596       ·   [GD] ellipse
597
598           "ellipse()" method added in GD 2.07.
599
600           If your GD version is smaller than 2.07 and you use "ellipse", the
601           "default" style will be returned.
602
603           If your GD is smaller than 2.07 and you use "ec", only the circles
604           will be drawn.
605

SUPPORT

640   BUG REPORTS
641       All bug reports and wishlist items must be reported via the CPAN RT
642       system. It is accessible at
643       http://rt.cpan.org/NoAuth/Bugs.html?Dist=GD-SecurityImage
644       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=GD-SecurityImage>.
645
646   DISCUSSION FORUM
647       "CPAN::Forum" is a place for discussing "CPAN" modules. It also has a
648       "GD::SecurityImage" section at
649       http://www.cpanforum.com/dist/GD-SecurityImage
650       <http://www.cpanforum.com/dist/GD-SecurityImage>.
651
652   RATINGS
653       If you like or hate or have some suggestions about "GD::SecurityImage",
654       you can comment/rate the distribution via the "CPAN Ratings" system:
655       http://cpanratings.perl.org/dist/GD-SecurityImage
656       <http://cpanratings.perl.org/dist/GD-SecurityImage>.
657

AUTHOR

659       Burak Guersoy, <burak@cpan.org>
660

COPYRIGHT

662       Copyright 2004-2008 Burak Guersoy. All rights reserved.
663

LICENSE

665       This library is free software; you can redistribute it and/or modify it
666       under the same terms as Perl itself, either Perl version 5.8.8 or, at
667       your option, any later version of Perl 5 you may have available.
668
669
670
671perl v5.12.1                      2010-07-23              GD::SecurityImage(3)