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

DESCRIPTION

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

COLOR PARAMETERS

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

METHODS

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

UTILITY METHODS

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

EXAMPLES

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

ERROR HANDLING

474       "die" is called in some methods if something fails. You may need to
475       "eval" your code to catch exceptions.
476

TIPS

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

BUGS

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

COMMON ERRORS

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

CAVEAT EMPTOR

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

SUPPORT

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

AUTHOR

660       Burak Gursoy <burak@cpan.org>.
661

COPYRIGHT

663       Copyright 2004 - 2015 Burak Gursoy. All rights reserved.
664

LICENSE

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