.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GD::SecurityImage 3pm" .TH GD::SecurityImage 3pm "2015-06-19" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" GD::SecurityImage \- Security image (captcha) generator. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use GD::SecurityImage; \& \& # Create a normal image \& my $image = GD::SecurityImage\->new( \& width => 80, \& height => 30, \& lines => 10, \& gd_font => \*(Aqgiant\*(Aq, \& ); \& $image\->random( $your_random_str ); \& $image\->create( normal => \*(Aqrect\*(Aq ); \& my($image_data, $mime_type, $random_number) = $image\->out; .Ve .PP or .PP .Vb 12 \& # use external ttf font \& my $image = GD::SecurityImage\->new( \& width => 100, \& height => 40, \& lines => 10, \& font => "/absolute/path/to/your.ttf", \& scramble => 1, \& ); \& $image\->random( $your_random_str ); \& $image\->create( ttf => \*(Aqdefault\*(Aq ); \& $image\->particle; \& my($image_data, $mime_type, $random_number) = $image\->out; .Ve .PP or you can just say (most of the public methods can be chained) .PP .Vb 1 \& my($image, $type, $rnd) = GD::SecurityImage\->new\->random\->create\->particle\->out; .Ve .PP to create a security image with the default settings. But that may not be useful. If you \f(CW\*(C`require\*(C'\fR the module, you \fBmust\fR import it: .PP .Vb 2 \& require GD::SecurityImage; \& GD::SecurityImage\->import; .Ve .PP The module also supports \f(CW\*(C`Image::Magick\*(C'\fR, but the default interface uses the \f(CW\*(C`GD\*(C'\fR module. To enable \f(CW\*(C`Image::Magick\*(C'\fR support, you must call the module with the \f(CW\*(C`use_magick\*(C'\fR option: .PP .Vb 1 \& use GD::SecurityImage use_magick => 1; .Ve .PP If you \f(CW\*(C`require\*(C'\fR the module, you \fBmust\fR import it: .PP .Vb 2 \& require GD::SecurityImage; \& GD::SecurityImage\->import(use_magick => 1); .Ve .PP The module does not \fIexport\fR anything actually. But \f(CW\*(C`import\*(C'\fR loads the necessary sub modules. If you don' t \f(CW\*(C`import\*(C'\fR, the required modules will not be loaded and probably, you'll \f(CW\*(C`die()\*(C'\fR. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This document describes version \f(CW1.73\fR of \f(CW\*(C`GD::SecurityImage\*(C'\fR released on \f(CW\*(C`21 January 2015\*(C'\fR. .PP The (so called) \fI\*(L"Security Images\*(R"\fR are so popular. Most internet software use these in their registration screens to block robot programs (which may register tons of fake member accounts). Security images are basicaly, graphical \fB\s-1CAPTCHA\s0\fRs (\fBC\fRompletely \fBA\fRutomated \fBP\fRublic \&\fBT\fRuring Test to Tell \fBC\fRomputers and \fBH\fRumans \fBA\fRpart). This module gives you a basic interface to create such an image. The final output is the actual graphic data, the mime type of the graphic and the created random string. The module also has some \fI\*(L"styles\*(R"\fR that are used to create the background (or foreground) of the image. .PP If you are an \f(CW\*(C`Authen::Captcha\*(C'\fR user, see GD::SecurityImage::AC for migration from \f(CW\*(C`Authen::Captcha\*(C'\fR to \f(CW\*(C`GD::SecurityImage\*(C'\fR. .PP This module is \fBjust an image generator\fR. Not a \fIcaptcha handler\fR. The validation of the generated graphic is left to your programming taste. But there are some \fIcaptcha handlers\fR for several Perl FrameWorks. If you are an user of one of these frameworks, see \&\*(L"GD::SecurityImage Implementations\*(R" in \*(L"\s-1SEE ALSO\*(R"\s0 section for information. .SH "COLOR PARAMETERS" .IX Header "COLOR PARAMETERS" This module can use both \s-1RGB\s0 and \s-1HEX\s0 values as the color parameters. \s-1HEX\s0 values are recommended, since they are widely used and recognised. .PP .Vb 3 \& $color = \*(Aq#80C0F0\*(Aq; # HEX \& $color2 = [15, 100, 75]; # RGB \& $i\->create($meth, $style, $color, $color2) \& \& $i\->create(ttf => \*(Aqbox\*(Aq, \*(Aq#80C0F0\*(Aq, \*(Aq#0F644B\*(Aq) .Ve .PP \&\s-1RGB\s0 values must be passed as an array reference including the three \&\fI\f(BIR\fIed\fR, \fI\f(BIG\fIreen\fR and \fI\f(BIB\fIlue\fR values. .PP Color conversion is transparent to the user. You can use hex values under both \f(CW\*(C`GD\*(C'\fR and \f(CW\*(C`Image::Magick\*(C'\fR. They' ll be automagically converted to \s-1RGB\s0 if you are under \f(CW\*(C`GD\*(C'\fR. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" The constructor. \f(CW\*(C`new()\*(C'\fR method takes several arguments. These arguments are listed below. .IP "width" 4 .IX Item "width" The width of the image (in pixels). .IP "height" 4 .IX Item "height" The height of the image (in pixels). .IP "ptsize" 4 .IX Item "ptsize" Numerical value. The point size of the ttf character. Only necessarry if you want to use a ttf font in the image. .IP "lines" 4 .IX Item "lines" The number of lines that you' ll see in the background of the image. The alignment of lines can be vertical, horizontal or angled or all of them. If you increase this parameter' s value, the image will be more cryptic. .IP "font" 4 .IX Item "font" The absolute path to your TrueType (.ttf) font file. Be aware that relative font paths are not recognized due to problems in the \f(CW\*(C`libgd\*(C'\fR library. .Sp If you are sure that you've set this parameter to a correct value and you get warnings or you get an empty image, be sure that your path does not include spaces in it. It looks like libgd also have problems with this kind of paths (eg: '/Documents and Settings/user' under Windows). .Sp Set this parameter if you want to use ttf in your image. .IP "gd_font" 4 .IX Item "gd_font" If you want to use the default interface, set this parameter. The recognized values are \f(CW\*(C`Small\*(C'\fR, \f(CW\*(C`Large\*(C'\fR, \f(CW\*(C`MediumBold\*(C'\fR, \f(CW\*(C`Tiny\*(C'\fR, \f(CW\*(C`Giant\*(C'\fR. The names are case-insensitive; you can pass lower-cased parameters. .IP "bgcolor" 4 .IX Item "bgcolor" The background color of the image. .IP "send_ctobg" 4 .IX Item "send_ctobg" If has a true value, the random security code will be displayed in the background and the lines will pass over it. (send_ctobg = send code to background) .IP "frame" 4 .IX Item "frame" If has a true value, a frame will be added around the image. This option is enabled by default. .IP "scramble" 4 .IX Item "scramble" If set, the characters will be scrambled. If you enable this option, be sure to use a wider image, since the characters will be separated with three spaces. .IP "angle" 4 .IX Item "angle" Sets the angle for scrambled/normal characters. Beware that, if you pass an \f(CW\*(C`angle\*(C'\fR parameter, the characters in your random string will have a fixed angle. If you do not set an \f(CW\*(C`angle\*(C'\fR parameter, the angle(s) will be random. .Sp When the scramble option is not enabled, this parameter still controls the angle of the text. But, since the text will be centered inside the image, using this parameter without scramble option will require a taller image. Clipping will occur with smaller height values. .Sp Unlike the \s-1GD\s0 interface, \f(CW\*(C`angle\*(C'\fR is in \f(CW\*(C`degree\*(C'\fRs and can take values between \f(CW0\fR and \f(CW360\fR. .IP "thickness" 4 .IX Item "thickness" Sets the line drawing width. Can take numerical values. Default values are \f(CW1\fR for \s-1GD\s0 and \f(CW0.6\fR for Image:Magick. .IP "rndmax" 4 .IX Item "rndmax" The minimum length of the random string. Default value is \f(CW6\fR. .IP "rnd_data" 4 .IX Item "rnd_data" Default character set used to create the random string is \f(CW0..9\fR. But, if you want to use letters also, you can set this parameter. This parameter takes an array reference as the value. .Sp \&\fBNot necessary and will not be used if you pass your own random\fR \&\fBstring.\fR .SS "random" .IX Subsection "random" Creates the random security string or \fBsets the random string\fR to the value you have passed. If you pass your own random string, be aware that it must be at least six (defined in \f(CW\*(C`rndmax\*(C'\fR) characters long. .SS "random_str" .IX Subsection "random_str" Returns the random string. Must be called after \f(CW\*(C`random()\*(C'\fR. .SS "create" .IX Subsection "create" This method creates the actual image. It takes four arguments, but none are mandatory. .PP .Vb 1 \& $image\->create($method, $style, $text_color, $line_color); .Ve .PP \&\f(CW$method\fR can be \fB\f(CB\*(C`normal\*(C'\fB\fR or \fB\f(CB\*(C`ttf\*(C'\fB\fR. .PP \&\f(CW$style\fR can be one of the following (some of the styles may not work if you are using a really old version of \s-1GD\s0): .IP "\fBdefault\fR" 4 .IX Item "default" The default style. Draws horizontal, vertical and angular lines. .IP "\fBrect\fR" 4 .IX Item "rect" Draws horizontal and vertical lines .IP "\fBbox\fR" 4 .IX Item "box" Draws two filled rectangles. .Sp The \f(CW\*(C`lines\*(C'\fR option passed to new, controls the size of the inner rectangle for this style. If you increase the \f(CW\*(C`lines\*(C'\fR, you'll get a smaller internal rectangle. Using smaller values like \f(CW5\fR can be better. .IP "\fBcircle\fR" 4 .IX Item "circle" Draws circles. .IP "\fBellipse\fR" 4 .IX Item "ellipse" Draws ellipses. .IP "\fBec\fR" 4 .IX Item "ec" This is the combination of ellipse and circle styles. Draws both ellipses and circles. .IP "\fBblank\fR" 4 .IX Item "blank" Draws nothing. See \*(L"\s-1OTHER USES\*(R"\s0. .PP \&\fINote\fR: if you have a (too) old version of \s-1GD,\s0 you may not be able to use some of the styles. .PP You can use this code to get all available style names: .PP .Vb 1 \& my @styles = grep {s/^style_//} keys %GD::SecurityImage::Styles::; .Ve .PP The last two arguments (\f(CW$text_color\fR and \f(CW$line_color\fR) are the colors used in the image (text and line color \*(-- respectively): .PP .Vb 2 \& $image\->create($method, $style, [0,0,0], [200,200,200]); \& $image\->create($method, $style, \*(Aq#000000\*(Aq, \*(Aq#c8c8c8\*(Aq); .Ve .SS "particle" .IX Subsection "particle" Must be called after create. .PP Adds random dots to the image. They'll cover all over the surface. Accepts two parameters; the density (number) of the particles and the maximum number of dots around the main dot. .PP .Vb 1 \& $image\->particle($density, $maxdots); .Ve .PP Default value of \f(CW$density\fR is dependent on your image' s width or height value. The greater value of width and height is taken and multiplied by twenty. So; if your width is \f(CW200\fR and height is \f(CW70\fR, \&\f(CW$density\fR is \f(CW\*(C`200 * 20 = 4000\*(C'\fR (unless you pass your own value). The default value of \f(CW$density\fR can be too much for smaller images. .PP \&\f(CW$maxdots\fR defines the maximum number of dots near the default dot. Default value is \f(CW1\fR. If you set it to \f(CW4\fR, The selected pixel and 3 other pixels near it will be used and colored. .PP The color of the particles are the same as the color of your text (defined in create). .SS "info_text" .IX Subsection "info_text" This method must be called after create. If you call it early, you'll die. \f(CW\*(C`info_text\*(C'\fR adds an extra text to the generated image. You can also put a strip under the text. The purpose of this method is to display additional information on the image. Copyright information can be an example for that. .PP .Vb 9 \& $image\->info_text( \& x => \*(Aqright\*(Aq, \& y => \*(Aqup\*(Aq, \& gd => 1, \& strip => 1, \& color => \*(Aq#000000\*(Aq, \& scolor => \*(Aq#FFFFFF\*(Aq, \& text => \*(AqGenerated by GD::SecurityImage\*(Aq, \& ); .Ve .PP Options: .IP "x" 4 .IX Item "x" Controls the horizontal location of the information text. Can be either \f(CW\*(C`left\*(C'\fR or \f(CW\*(C`right\*(C'\fR. .IP "y" 4 .IX Item "y" Controls the vertical location of the information text. Can be either \f(CW\*(C`up\*(C'\fR or \f(CW\*(C`down\*(C'\fR. .IP "strip" 4 .IX Item "strip" If has a true value, a strip will be added to the background of the information text. .IP "gd" 4 .IX Item "gd" This option can only be used under \f(CW\*(C`GD\*(C'\fR. Has no effect under Image::Magick. If has a true value, the standard \s-1GD\s0 font \f(CW\*(C`Tiny\*(C'\fR will be used for the information text. .Sp If this option is not present or has a false value, the \s-1TTF\s0 font parameter passed to \f(CW\*(C`new\*(C'\fR will be used instead. .IP "ptsize" 4 .IX Item "ptsize" The ptsize value of the information text to be used with the \s-1TTF\s0 font. \&\s-1TTF\s0 font parameter can not be set with \f(CW\*(C`info_text()\*(C'\fR. The value passed to \f(CW\*(C`new()\*(C'\fR will be used instead. .IP "color" 4 .IX Item "color" The color of the information text. .IP "scolor" 4 .IX Item "scolor" The color of the strip. .IP "text" 4 .IX Item "text" This parameter controls the displayed text. If you want to display long texts, be sure to adjust the image, or clipping will occur. .SS "out" .IX Subsection "out" This method finally returns the created image, the mime type of the image and the random number(s) generated. Older versions of \s-1GD\s0 only support \&\f(CW\*(C`gif\*(C'\fR type, while new versions support \f(CW\*(C`jpeg\*(C'\fR and \f(CW\*(C`png\*(C'\fR (\fBupdate\fR: beginning with v2.15, \s-1GD\s0 resumed gif support). .PP The returned mime type is \f(CW\*(C`png\*(C'\fR or \f(CW\*(C`gif\*(C'\fR or \f(CW\*(C`jpeg\*(C'\fR for \f(CW\*(C`GD\*(C'\fR and \&\f(CW\*(C`gif\*(C'\fR for \f(CW\*(C`Image::Magick\*(C'\fR (if you do not \f(CW\*(C`force\*(C'\fR some other format). .PP \&\f(CW\*(C`out\*(C'\fR method accepts arguments: .PP .Vb 1 \& @data = $image\->out(%args); .Ve .IP "force" 4 .IX Item "force" You can set the output format with the \f(CW\*(C`force\*(C'\fR parameter: .Sp .Vb 1 \& @data = $image\->out(force => \*(Aqpng\*(Aq); .Ve .Sp If \f(CW\*(C`png\*(C'\fR is supported by the interface (via \f(CW\*(C`GD\*(C'\fR or \f(CW\*(C`Image::Magick\*(C'\fR); you'll get a png image, if the interface does not support this format, \&\f(CW\*(C`out()\*(C'\fR method will use it's default configuration. .IP "compress" 4 .IX Item "compress" And with the \f(CW\*(C`compress\*(C'\fR parameter, you can define the compression for \f(CW\*(C`png\*(C'\fR and quality for \f(CW\*(C`jpeg\*(C'\fR: .Sp .Vb 2 \& @data = $image\->out(force => \*(Aqpng\*(Aq , compress => 1); \& @data = $image\->out(force => \*(Aqjpeg\*(Aq, compress => 100); .Ve .Sp When you use \f(CW\*(C`compress\*(C'\fR with \f(CW\*(C`png\*(C'\fR format, the value of \f(CW\*(C`compress\*(C'\fR is ignored and it is only checked if it has a true value. With \f(CW\*(C`png\*(C'\fR the compression will always be \f(CW9\fR (maximum compression). eg: .Sp .Vb 4 \& @data = $image\->out(force => \*(Aqpng\*(Aq , compress => 1); \& @data = $image\->out(force => \*(Aqpng\*(Aq , compress => 3); \& @data = $image\->out(force => \*(Aqpng\*(Aq , compress => 5); \& @data = $image\->out(force => \*(Aqpng\*(Aq , compress => 1500); .Ve .Sp All will default to \f(CW9\fR. But this will disable compression: .Sp .Vb 1 \& @data = $image\->out(force => \*(Aqpng\*(Aq , compress => 0); .Ve .Sp But the behaviour changes if the format is \f(CW\*(C`jpeg\*(C'\fR; the value of \&\f(CW\*(C`compress\*(C'\fR will be used for \f(CW\*(C`jpeg\*(C'\fR quality; which is in the range \&\f(CW1..100\fR. .Sp Compression and quality operations are disabled by default. .SS "raw" .IX Subsection "raw" Depending on your usage of the module; returns the raw \f(CW\*(C`GD::Image\*(C'\fR object: .PP .Vb 2 \& my $gd = $image\->raw; \& print $gd\->png; .Ve .PP or the raw \f(CW\*(C`Image::Magick\*(C'\fR object: .PP .Vb 2 \& my $magick = $image\->raw; \& $magick\->Write("gif:\-"); .Ve .PP Can be useful, if you want to modify the graphic yourself. If you want to get an \fIimage type\fR see the \f(CW\*(C`force\*(C'\fR option in \f(CW\*(C`out\*(C'\fR. .SS "gdbox_empty" .IX Subsection "gdbox_empty" See \*(L"path bug\*(R" in \*(L"\s-1GD\s0 bug\*(R" for usage and other information on this method. .SS "add_strip" .IX Subsection "add_strip" .SS "cconvert" .IX Subsection "cconvert" .SS "gdf" .IX Subsection "gdf" .SS "h2r" .IX Subsection "h2r" .SS "is_hex" .IX Subsection "is_hex" .SS "r2h" .IX Subsection "r2h" .SS "random_angle" .IX Subsection "random_angle" .SH "UTILITY METHODS" .IX Header "UTILITY METHODS" .SS "backends" .IX Subsection "backends" Returns a list of available GD::SecurityImage back-ends. .PP .Vb 1 \& my @be = GD::SecurityImage\->backends; .Ve .PP or .PP .Vb 1 \& my @be = $image\->backends; .Ve .PP If called in a void context, prints a verbose list of available GD::SecurityImage back-ends: .PP .Vb 3 \& Available back\-ends in GD::SecurityImage v1.55 are: \& GD \& Magick \& \& Search directories: \& /some/@INC/dir/containing/GDSI .Ve .PP you can see the output with this command: .PP .Vb 1 \& perl \-MGD::SecurityImage \-e \*(AqGD::SecurityImage\->backends\*(Aq .Ve .PP or under windows: .PP .Vb 1 \& perl \-MGD::SecurityImage \-e "GD::SecurityImage\->backends" .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" See the tests in the distribution. Also see the demo program \&\*(L"eg/demo.pl\*(R" for an \f(CW\*(C`Apache::Session\*(C'\fR implementation of \&\f(CW\*(C`GD::SecurityImage\*(C'\fR. .PP Download the distribution from a \s-1CPAN\s0 mirror near you, if you don't have the files. .SS "\s-1OTHER USES\s0" .IX Subsection "OTHER USES" \&\f(CW\*(C`GD::SecurityImage\*(C'\fR drawing capabilities can also be used for \&\fIcounter image\fR generation or displaying arbitrary messages: .PP .Vb 2 \& use CGI qw(header); \& use GD::SecurityImage 1.64; # we need the "blank" style \& \& my $font = "StayPuft.ttf"; \& my $rnd = "10.257"; # counter data \& \& my $image = GD::SecurityImage\->new( \& width => 140, \& height => 75, \& ptsize => 30, \& rndmax => 1, # keeping this low helps to display short strings \& frame => 0, # disable borders \& font => $font, \& ); \& \& $image\->random( $rnd ); \& # use the blank style, so that nothing will be drawn \& # to distort the image. \& $image\->create( ttf => \*(Aqblank\*(Aq, \*(Aq#CC8A00\*(Aq ); \& $image\->info_text( \& text => \*(AqYou are visitor number\*(Aq, \& ptsize => 10, \& strip => 0, \& color => \*(Aq#0094CC\*(Aq, \& ); \& $image\->info_text( \& text => \*(Aq( c ) 2 0 0 7 m y s i t e\*(Aq, \& ptsize => 10, \& strip => 0, \& color => \*(Aq#d7d7d7\*(Aq, \& y => \*(Aqdown\*(Aq, \& ); \& \& my($data, $mime, $random) = $image\->out; \& \& binmode STDOUT; \& print header \-type => "image/$mime"; \& print $data; .Ve .SH "ERROR HANDLING" .IX Header "ERROR HANDLING" \&\f(CW\*(C`die\*(C'\fR is called in some methods if something fails. You may need to \&\f(CW\*(C`eval\*(C'\fR your code to catch exceptions. .SH "TIPS" .IX Header "TIPS" If you look at the demo program (not just look at it, try to run it) you'll see that the random code changes after every request (successful or not). If you do not change the random code after a failed request and display the random code inside \s-1HTML \s0(like \fI\*(L"Wrong! It must be \*(R"\fR), then you are doing a logical mistake, since the user (or robot) can now copy & paste the random code into your validator without looking at the security image and will pass the test. Just don't do that. Random code must change after every validation. .PP If you want to be a little more strict, you can also add a timeout key to the session (this feature currently does not exits in the demo) and expire the related random code after the timeout. Since robots can call the image generator directly (without requiring the \s-1HTML\s0 form), they can examine the image for a while without changing it. A timeout implemetation may prevent this. .SH "BUGS" .IX Header "BUGS" See the \*(L"\s-1SUPPORT\*(R"\s0 section if you have a bug or request to report. .SS "Image::Magick bug" .IX Subsection "Image::Magick bug" There is a bug in PerlMagick' s \f(CW\*(C`QueryFontMetrics()\*(C'\fR method. ImageMagick versions smaller than 6.0.4 is affected. Below text is from the ImageMagick 6.0.4 Changelog: . .PP "2004\-05\-06 PerlMagick's \f(CW\*(C`QueryFontMetrics()\*(C'\fR incorrectly reports `unrecognized attribute'` for the `font' attribute." .PP Please upgrade to ImageMagick 6.0.4 or any newer version, if your ImageMagick version is smaller than 6.0.4 and you want to use Image::Magick as the backend for GD::SecurityImage. .SS "\s-1GD\s0 bug" .IX Subsection "GD bug" \fIpath bug\fR .IX Subsection "path bug" .PP libgd and \s-1GD\s0.pm don't like relative paths and paths that have spaces in them. If you pass a font path that is not an \fBexact path\fR or a path that have a space in it, you may get an empty image. .PP To check if the module failed to find the ttf font (when using \f(CW\*(C`GD\*(C'\fR), a new method added: \f(CW\*(C`gdbox_empty()\*(C'\fR. It must be called after \f(CW\*(C`create()\*(C'\fR: .PP .Vb 2 \& $image\->create; \& die "Error loading ttf font for GD: $@" if $image\->gdbox_empty; .Ve .PP \&\f(CW\*(C`gdbox_empty()\*(C'\fR always returns false, if you are using \f(CW\*(C`Image::Magick\*(C'\fR. .SH "COMMON ERRORS" .IX Header "COMMON ERRORS" .SS "Wrong \s-1GD\s0 installation" .IX Subsection "Wrong GD installation" I got some error reports saying that GD::SecurityImage dies with this error: .PP .Vb 2 \& Can\*(Aqt locate object method "new" via package "GD::Image" \& (perhaps you forgot to load "GD::Image"?) at ... .Ve .PP This is due to a \fIwrong\fR installation of the \s-1GD\s0 module. \s-1GD\s0 includes \f(CW\*(C`XS\*(C'\fR code and it needs to be compiled. You can't just copy/paste the \fI\s-1GD\s0.pm\fR and expect it to work. It will not. If you are under Windows and don't have a C compiler, you have to add new repositories to install \fI\s-1GD\s0\fR, since ActiveState' s own repositories don't include \fI\s-1GD\s0\fR. Randy Kobes and J\-L Morel have ppm repositories for both 5.6.x and 5.8.x and they both have \fI\s-1GD\s0\fR: .PP .Vb 2 \& http://www.bribes.org/perl/ppmdir.html \& http://theoryx5.uwinnipeg.ca/ .Ve .PP \&\fIbribes.org\fR also has a \fIGD::SecurityImage\fR ppd, so you can just install \fIGD::SecurityImage\fR from that repository. .SS "libgd errors" .IX Subsection "libgd errors" There are some issues related to wrong/incomplete compiling of libgd and old/new version conflicts. .PP \fIlibgd without \s-1TTF\s0 support\fR .IX Subsection "libgd without TTF support" .PP If your libgd is compiled without \s-1TTF\s0 support, you'll get an \fIempty\fR image. The lines will be drawn, but there will be no text. You can check it with \*(L"gdbox_empty\*(R" method. .PP \fI\s-1GIF \-\s0 Old libgd or libgd without \s-1GIF\s0 support enabled\fR .IX Subsection "GIF - Old libgd or libgd without GIF support enabled" .PP If your \s-1GD\s0 has a \f(CW\*(C`gif\*(C'\fR method, but you get empty images with \f(CW\*(C`gif()\*(C'\fR method, you have to update your libgd or compile it with \s-1GIF\s0 enabled. .PP You can test if \f(CW\*(C`gif\*(C'\fR is working from the command line: .PP .Vb 1 \& perl \-MGD \-e \*(Aq$_=GD::Image\->new;$_\->colorAllocate(0,0,0);print$_\->gif\*(Aq .Ve .PP or under windows: .PP .Vb 1 \& perl \-MGD \-e "$_=GD::Image\->new;$_\->colorAllocate(0,0,0);print$_\->gif" .Ve .PP Conclusions: .IP "\(bu" 4 If it dies, your \s-1GD\s0 is very old. .IP "\(bu" 4 If it prints nothing, your libgd was compiled without \s-1GIF\s0 enabled (upgrade or re-compile). .IP "\(bu" 4 If it prints out a junk that starts with 'GIF87a', everything is \s-1OK.\s0 .SH "CAVEAT EMPTOR" .IX Header "CAVEAT EMPTOR" .IP "\(bu" 4 Using the default library \f(CW\*(C`GD\*(C'\fR is a better choice. Since it is faster and does not use that much memory, while \f(CW\*(C`Image::Magick\*(C'\fR is slower and uses more memory. .IP "\(bu" 4 The internal random code generator is used \fBonly\fR for demonstration purposes for this module. It may not be \fIeffective\fR. You must supply your own random code and use this module to display it. .IP "\(bu" 4 \&\fB[\s-1GD\s0] png compression\fR .Sp Support for compression level argument to \fIpng()\fR added in v2.07. If your \s-1GD\s0 version is smaller than this, compress option to \f(CW\*(C`out()\*(C'\fR will be silently ignored. .IP "\(bu" 4 \&\fB[\s-1GD\s0] setThickness\fR .Sp setThickness implemented in \s-1GD\s0 v2.07. If your \s-1GD\s0 version is smaller than that and you set thickness option, nothing will happen. .IP "\(bu" 4 \&\fB[\s-1GD\s0] ellipse\fR .Sp \&\f(CW\*(C`ellipse()\*(C'\fR method added in \s-1GD 2.07. \s0 .Sp If your \s-1GD\s0 version is smaller than 2.07 and you use \f(CW\*(C`ellipse\*(C'\fR, the \f(CW\*(C`default\*(C'\fR style will be returned. .Sp If your \s-1GD\s0 is smaller than 2.07 and you use \f(CW\*(C`ec\*(C'\fR, only the circles will be drawn. .SH "SEE ALSO" .IX Header "SEE ALSO" .SS "Other \s-1CAPTCHA\s0 Implementations & Perl Modules" .IX Subsection "Other CAPTCHA Implementations & Perl Modules" .IP "\(bu" 4 \&\s-1GD\s0, Image::Magick .IP "\(bu" 4 ImagePwd, Authen::Captcha. .IP "\(bu" 4 \&\f(CW\*(C`ImageCode\*(C'\fR Perl Module (commercial): . .IP "\(bu" 4 The \s-1CAPTCHA\s0 project: . .IP "\(bu" 4 A definition of \s-1CAPTCHA \s0(From Wikipedia, the free encyclopedia): . .IP "\(bu" 4 WebService::CaptchasDotNet: A Perl interface to \&\fIhttp://captchas.net\fR free captcha service. \fIcaptchas.net\fR also offers \fIaudio\fR captchas. .SS "GD::SecurityImage Implementations" .IX Subsection "GD::SecurityImage Implementations" .IP "\(bu" 4 GD::SecurityImage::AC: \f(CW\*(C`Authen::Captcha\*(C'\fR drop-in replacement module. .IP "\(bu" 4 Sledge::Plugin::Captcha .IP "\(bu" 4 Catalyst::Plugin::Captcha .IP "\(bu" 4 CGI::Application::Plugin::CAPTCHA .IP "\(bu" 4 Angerwhale::Controller::Captcha .SS "Software Using GD::SecurityImage" .IX Subsection "Software Using GD::SecurityImage" If your software uses \f(CW\*(C`GD::SecurityImage\*(C'\fR for captcha generation and want to appear in this document, contact the author. .SH "SUPPORT" .IX Header "SUPPORT" .SS "\s-1BUG REPORTS\s0" .IX Subsection "BUG REPORTS" All bug reports and wishlist items \fBmust\fR be reported via the \s-1CPAN RT\s0 system. It is accessible at . .SS "\s-1DISCUSSION FORUM\s0" .IX Subsection "DISCUSSION FORUM" \&\f(CW\*(C`CPAN::Forum\*(C'\fR is a place for discussing \f(CW\*(C`CPAN\*(C'\fR modules. It also has a \f(CW\*(C`GD::SecurityImage\*(C'\fR section at . .SS "\s-1RATINGS\s0" .IX Subsection "RATINGS" If you like or hate or have some suggestions about \&\f(CW\*(C`GD::SecurityImage\*(C'\fR, you can comment/rate the distribution via the \f(CW\*(C`CPAN Ratings\*(C'\fR system: . .SH "AUTHOR" .IX Header "AUTHOR" Burak Gursoy . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2004 \- 2015 Burak Gursoy. All rights reserved. .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.