1GD::SecurityImage(3) User Contributed Perl Documentation GD::SecurityImage(3)
2
3
4
6 GD::SecurityImage
7
9 version 1.75
10
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
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
86 GD::SecurityImage - Security image (captcha) generator.
87
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
106 new
107 The constructor. "new()" method takes several arguments. These
108 arguments 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
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
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
473 "die" is called in some methods if something fails. You may need to
474 "eval" your code to catch exceptions.
475
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
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
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
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
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
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.30.1 2020-01-30 GD::SecurityImage(3)