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

NAME

6       GD::SecurityImage
7

VERSION

9       version 1.75
10

SYNOPSIS

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

DESCRIPTION

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

NAME

86       GD::SecurityImage - Security image (captcha) generator.
87

COLOR PARAMETERS

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

METHODS

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

UTILITY METHODS

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

EXAMPLES

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

ERROR HANDLING

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

TIPS

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

BUGS

494       See the "SUPPORT" section if you have a bug or request to report.
495
496   GD bug
497       path bug
498
499       libgd and GD.pm don't like relative paths and paths that have spaces in
500       them. If you pass a font path that is not an exact path or a path that
501       have a space in it, you may get an empty image.
502
503       To check if the module failed to find the ttf font (when using "GD"), a
504       new method added: gdbox_empty(). It must be called after create():
505
506          $image->create;
507          die "Error loading ttf font for GD: $@" if $image->gdbox_empty;
508
509       gdbox_empty() always returns false, if you are using "Image::Magick".
510

COMMON ERRORS

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

CAVEAT EMPTOR

567       •   Using the default library "GD" is a better choice. Since it is
568           faster and does not use that much memory, while "Image::Magick" is
569           slower and uses more memory.
570
571       •   The internal random code generator is used only for demonstration
572           purposes for this module. It may not be effective. You must supply
573           your own random code and use this module to display it.
574

SEE ALSO

576   Other CAPTCHA Implementations & Perl Modules
577       •   GD, Image::Magick
578
579       •   ImagePwd, Authen::Captcha.
580
581       •   "ImageCode" Perl Module (commercial):
582           <http://www.progland.com/ImageCode.html>.
583
584       •   The CAPTCHA project: <http://www.captcha.net/>.
585
586       •   A definition of CAPTCHA (From Wikipedia, the free encyclopedia):
587           <http://en.wikipedia.org/wiki/Captcha>.
588
589       •   WebService::CaptchasDotNet: A Perl interface to http://captchas.net
590           free captcha service. captchas.net also offers audio captchas.
591
592   GD::SecurityImage Implementations
593       •   GD::SecurityImage::AC: "Authen::Captcha" drop-in replacement
594           module.
595
596       •   Sledge::Plugin::Captcha
597
598       •   Catalyst::Plugin::Captcha
599
600       •   CGI::Application::Plugin::CAPTCHA
601
602       •   Angerwhale::Controller::Captcha
603

AUTHOR

605       Burak Gursoy <burak@cpan.org>
606
608       This software is copyright (c) 2004 by Burak Gursoy.
609
610       This is free software; you can redistribute it and/or modify it under
611       the same terms as the Perl 5 programming language system itself.
612
613
614
615perl v5.36.0                      2023-01-20              GD::SecurityImage(3)
Impressum