Provided by: libgd-securityimage-perl_1.72-1_all bug

NAME

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

SYNOPSIS

          use GD::SecurityImage;

          # Create a normal image
          my $image = GD::SecurityImage->new(
                         width   => 80,
                         height  => 30,
                         lines   => 10,
                         gd_font => 'giant',
                      );
             $image->random( $your_random_str );
             $image->create( normal => 'rect' );
          my($image_data, $mime_type, $random_number) = $image->out;

       or

          # 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 => 'default' );
             $image->particle;
          my($image_data, $mime_type, $random_number) = $image->out;

       or you can just say (most of the public methods can be chained)

          my($image, $type, $rnd) = GD::SecurityImage->new->random->create->particle->out;

       to create a security image with the default settings. But that may not be useful. If you
       "require" the module, you must import it:

          require GD::SecurityImage;
          GD::SecurityImage->import;

       The module also supports "Image::Magick", but the default interface uses the "GD" module.
       To enable "Image::Magick" support, you must call the module with the "use_magick" option:

          use GD::SecurityImage use_magick => 1;

       If you "require" the module, you must import it:

          require GD::SecurityImage;
          GD::SecurityImage->import(use_magick => 1);

       The module does not export anything actually. But "import" loads the necessary sub
       modules. If you don' t "import", the required modules will not be loaded and probably,
       you'll "die()".

DESCRIPTION

       This document describes version 1.72 of "GD::SecurityImage" released on "27 August 2012".

       The (so called) "Security Images" 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 CAPTCHAs (Completely Automated
       Public Turing Test to Tell Computers and Humans Apart). 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 "styles" that
       are used to create the background (or foreground) of the image.

       If you are an "Authen::Captcha" user, see GD::SecurityImage::AC for migration from
       "Authen::Captcha" to "GD::SecurityImage".

       This module is just an image generator. Not a captcha handler.  The validation of the
       generated graphic is left to your programming taste. But there are some captcha handlers
       for several Perl FrameWorks.  If you are an user of one of these frameworks, see
       "GD::SecurityImage Implementations" in "SEE ALSO" section for information.

COLOR PARAMETERS

       This module can use both RGB and HEX values as the color parameters. HEX values are
       recommended, since they are widely used and recognised.

          $color  = '#80C0F0';     # HEX
          $color2 = [15, 100, 75]; # RGB
          $i->create($meth, $style, $color, $color2)

          $i->create(ttf => 'box', '#80C0F0', '#0F644B')

       RGB values must be passed as an array reference including the three Red, Green and Blue
       values.

       Color conversion is transparent to the user. You can use hex values under both "GD" and
       "Image::Magick". They' ll be automagically converted to RGB if you are under "GD".

METHODS

   new
       The constructor. "new()" method takes several arguments. These arguments are listed below.

       width
           The width of the image (in pixels).

       height
           The height of the image (in pixels).

       ptsize
           Numerical value. The point size of the ttf character.  Only necessarry if you want to
           use a ttf font in the image.

       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.

       font
           The absolute path to your TrueType (.ttf) font file. Be aware that relative font paths
           are not recognized due to problems in the "libgd" library.

           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).

           Set this parameter if you want to use ttf in your image.

       gd_font
           If you want to use the default interface, set this parameter. The recognized values
           are "Small", "Large", "MediumBold", "Tiny", "Giant".  The names are case-insensitive;
           you can pass lower-cased parameters.

       bgcolor
           The background color of the image.

       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)

       frame
           If has a true value, a frame will be added around the image. This option is enabled by
           default.

       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.

       angle
           Sets the angle for scrambled/normal characters. Beware that, if you pass an "angle"
           parameter, the characters in your random string will have a fixed angle. If you do not
           set an "angle" parameter, the angle(s) will be random.

           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.

           Unlike the GD interface, "angle" is in "degree"s and can take values between 0 and
           360.

       thickness
           Sets the line drawing width. Can take numerical values.  Default values are 1 for GD
           and 0.6 for Image:Magick.

       rndmax
           The minimum length of the random string. Default value is 6.

       rnd_data
           Default character set used to create the random string is 0..9.  But, if you want to
           use letters also, you can set this parameter.  This parameter takes an array reference
           as the value.

           Not necessary and will not be used if you pass your own random string.

   random
       Creates the random security string or sets the random string to the value you have passed.
       If you pass your own random string, be aware that it must be at least six (defined in
       "rndmax") characters long.

   random_str
       Returns the random string. Must be called after "random()".

   create
       This method creates the actual image. It takes four arguments, but none are mandatory.

          $image->create($method, $style, $text_color, $line_color);

       $method can be "normal" or "ttf".

       $style can be one of the following (some of the styles may not work if you are using a
       really old version of GD):

       default
           The default style. Draws horizontal, vertical and angular lines.

       rect
           Draws horizontal and vertical lines

       box Draws two filled rectangles.

           The "lines" option passed to new, controls the size of the inner rectangle for this
           style. If you increase the "lines", you'll get a smaller internal rectangle. Using
           smaller values like 5 can be better.

       circle
           Draws circles.

       ellipse
           Draws ellipses.

       ec  This is the combination of ellipse and circle styles. Draws both ellipses and circles.

       blank
           Draws nothing. See "OTHER USES".

       Note: if you have a (too) old version of GD, you may not be able to use some of the
       styles.

       You can use this code to get all available style names:

          my @styles = grep {s/^style_//} keys %GD::SecurityImage::Styles::;

       The last two arguments ($text_color and $line_color) are the colors used in the image
       (text and line color -- respectively):

          $image->create($method, $style, [0,0,0], [200,200,200]);
          $image->create($method, $style, '#000000', '#c8c8c8');

   particle
       Must be called after create.

       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.

          $image->particle($density, $maxdots);

       Default value of $density 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 200 and
       height is 70, $density is "200 * 20 = 4000" (unless you pass your own value).  The default
       value of $density can be too much for smaller images.

       $maxdots defines the maximum number of dots near the default dot.  Default value is 1. If
       you set it to 4, The selected pixel and 3 other pixels near it will be used and colored.

       The color of the particles are the same as the color of your text (defined in create).

   info_text
       This method must be called after create. If you call it early, you'll die. "info_text"
       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.

          $image->info_text(
             x      => 'right',
             y      => 'up',
             gd     => 1,
             strip  => 1,
             color  => '#000000',
             scolor => '#FFFFFF',
             text   => 'Generated by GD::SecurityImage',
          );

       Options:

       x   Controls the horizontal location of the information text. Can be either "left" or
           "right".

       y   Controls the vertical location of the information text. Can be either "up" or "down".

       strip
           If has a true value, a strip will be added to the background of the information text.

       gd  This option can only be used under "GD". Has no effect under Image::Magick. If has a
           true value, the standard GD font "Tiny" will be used for the information text.

           If this option is not present or has a false value, the TTF font parameter passed to
           "new" will be used instead.

       ptsize
           The ptsize value of the information text to be used with the TTF font.  TTF font
           parameter can not be set with "info_text()". The value passed to "new()" will be used
           instead.

       color
           The color of the information text.

       scolor
           The color of the strip.

       text
           This parameter controls the displayed text. If you want to display long texts, be sure
           to adjust the image, or clipping will occur.

   out
       This method finally returns the created image, the mime type of the image and the random
       number(s) generated. Older versions of GD only support "gif" type, while new versions
       support "jpeg" and "png" (update: beginning with v2.15, GD resumed gif support).

       The returned mime type is "png" or "gif" or "jpeg" for "GD" and "gif" for "Image::Magick"
       (if you do not "force" some other format).

       "out" method accepts arguments:

          @data = $image->out(%args);

       force
           You can set the output format with the "force" parameter:

              @data = $image->out(force => 'png');

           If "png" is supported by the interface (via "GD" or "Image::Magick"); you'll get a png
           image, if the interface does not support this format, "out()" method will use it's
           default configuration.

       compress
           And with the "compress" parameter, you can define the compression for "png" and
           quality for "jpeg":

              @data = $image->out(force => 'png' , compress => 1);
              @data = $image->out(force => 'jpeg', compress => 100);

           When you use "compress" with "png" format, the value of "compress" is ignored and it
           is only checked if it has a true value. With "png" the compression will always be 9
           (maximum compression). eg:

              @data = $image->out(force => 'png' , compress => 1);
              @data = $image->out(force => 'png' , compress => 3);
              @data = $image->out(force => 'png' , compress => 5);
              @data = $image->out(force => 'png' , compress => 1500);

           All will default to 9. But this will disable compression:

              @data = $image->out(force => 'png' , compress => 0);

           But the behaviour changes if the format is "jpeg"; the value of "compress" will be
           used for "jpeg" quality; which is in the range 1..100.

           Compression and quality operations are disabled by default.

   raw
       Depending on your usage of the module; returns the raw "GD::Image" object:

          my $gd = $image->raw;
          print $gd->png;

       or the raw "Image::Magick" object:

          my $magick = $image->raw;
          $magick->Write("gif:-");

       Can be useful, if you want to modify the graphic yourself. If you want to get an image
       type see the "force" option in "out".

   gdbox_empty
       See "path bug" in "GD bug" for usage and other information on this method.

   add_strip
   cconvert
   gdf
   h2r
   is_hex
   r2h
   random_angle

UTILITY METHODS

   backends
       Returns a list of available GD::SecurityImage back-ends.

          my @be = GD::SecurityImage->backends;

       or

          my @be = $image->backends;

       If called in a void context, prints a verbose list of available GD::SecurityImage back-
       ends:

          Available back-ends in GD::SecurityImage v1.55 are:
                  GD
                  Magick

          Search directories:
                     /some/@INC/dir/containing/GDSI

       you can see the output with this command:

          perl -MGD::SecurityImage -e 'GD::SecurityImage->backends'

       or under windows:

          perl -MGD::SecurityImage -e "GD::SecurityImage->backends"

EXAMPLES

       See the tests in the distribution. Also see the demo program "eg/demo.pl" for an
       "Apache::Session" implementation of "GD::SecurityImage".

       Download the distribution from a CPAN mirror near you, if you don't have the files.

   OTHER USES
       "GD::SecurityImage" drawing capabilities can also be used for counter image generation or
       displaying arbitrary messages:

          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 => 'blank', '#CC8A00' );
          $image->info_text(
             text   => 'You are visitor number',
             ptsize => 10,
             strip  =>  0,
             color  => '#0094CC',
          );
          $image->info_text(
             text   => '( c ) 2 0 0 7   m y s i t e',
             ptsize => 10,
             strip  =>  0,
             color  => '#d7d7d7',
             y      => 'down',
          );

          my($data, $mime, $random) = $image->out;

          binmode STDOUT;
          print header -type => "image/$mime";
          print $data;

ERROR HANDLING

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

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 HTML (like "Wrong!
       It must be <random>"), 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.

       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 HTML form), they can examine the image for a while without changing it. A timeout
       implemetation may prevent this.

BUGS

       See the "SUPPORT" section if you have a bug or request to report.

   Image::Magick bug
       There is a bug in PerlMagick' s "QueryFontMetrics()" method. ImageMagick versions smaller
       than 6.0.4 is affected. Below text is from the ImageMagick 6.0.4 Changelog:
       <http://www.imagemagick.org/www/Changelog.html>.

       "2004-05-06 PerlMagick's "QueryFontMetrics()" incorrectly reports `unrecognized
       attribute'` for the `font' attribute."

       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.

   GD bug
       path bug

       libgd and GD.pm don't like relative paths and paths that have spaces in them. If you pass
       a font path that is not an exact path or a path that have a space in it, you may get an
       empty image.

       To check if the module failed to find the ttf font (when using "GD"), a new method added:
       "gdbox_empty()". It must be called after "create()":

          $image->create;
          die "Error loading ttf font for GD: $@" if $image->gdbox_empty;

       "gdbox_empty()" always returns false, if you are using "Image::Magick".

COMMON ERRORS

   Wrong GD installation
       I got some error reports saying that GD::SecurityImage dies with this error:

          Can't locate object method "new" via package "GD::Image"
          (perhaps you forgot to load "GD::Image"?) at ...

       This is due to a wrong installation of the GD module. GD includes "XS" code and it needs
       to be compiled. You can't just copy/paste the GD.pm 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 GD, since ActiveState' s own repositories don't include GD. Randy Kobes and J-L
       Morel have ppm repositories for both 5.6.x and 5.8.x and they both have GD:

          http://www.bribes.org/perl/ppmdir.html
          http://theoryx5.uwinnipeg.ca/

       bribes.org also has a GD::SecurityImage ppd, so you can just install GD::SecurityImage
       from that repository.

   libgd errors
       There are some issues related to wrong/incomplete compiling of libgd and old/new version
       conflicts.

       libgd without TTF support

       If your libgd is compiled without TTF support, you'll get an empty image. The lines will
       be drawn, but there will be no text. You can check it with "gdbox_empty" method.

       GIF - Old libgd or libgd without GIF support enabled

       If your GD has a "gif" method, but you get empty images with "gif()" method, you have to
       update your libgd or compile it with GIF enabled.

       You can test if "gif" is working from the command line:

          perl -MGD -e '$_=GD::Image->new;$_->colorAllocate(0,0,0);print$_->gif'

       or under windows:

          perl -MGD -e "$_=GD::Image->new;$_->colorAllocate(0,0,0);print$_->gif"

       Conclusions:

       •   If it dies, your GD is very old.

       •   If it prints nothing, your libgd was compiled without GIF enabled (upgrade or re-
           compile).

       •   If it prints out a junk that starts with 'GIF87a', everything is OK.

CAVEAT EMPTOR

       •   Using the default library "GD" is a better choice. Since it is faster and does not use
           that much memory, while "Image::Magick" is slower and uses more memory.

       •   The internal random code generator is used only for demonstration purposes for this
           module. It may not be effective. You must supply your own random code and use this
           module to display it.

       •   [GD] png compression

           Support for compression level argument to png() added in v2.07. If your GD version is
           smaller than this, compress option to "out()" will be silently ignored.

       •   [GD] setThickness

           setThickness implemented in GD v2.07. If your GD version is smaller than that and you
           set thickness option, nothing will happen.

       •   [GD] ellipse

           "ellipse()" method added in GD 2.07.

           If your GD version is smaller than 2.07 and you use "ellipse", the "default" style
           will be returned.

           If your GD is smaller than 2.07 and you use "ec", only the circles will be drawn.

SEE ALSO

   Other CAPTCHA Implementations & Perl Modules
       •   GD, Image::Magick

       •   ImagePwd, Authen::Captcha.

       •   "ImageCode" Perl Module (commercial): <http://www.progland.com/ImageCode.html>.

       •   The CAPTCHA project: <http://www.captcha.net/>.

       •   A definition of CAPTCHA (From Wikipedia, the free encyclopedia):
           <http://en.wikipedia.org/wiki/Captcha>.

       •   WebService::CaptchasDotNet: A Perl interface to http://captchas.net free captcha
           service. captchas.net also offers audio captchas.

   GD::SecurityImage Implementations
       •   GD::SecurityImage::AC: "Authen::Captcha" drop-in replacement module.

       •   Sledge::Plugin::Captcha

       •   Catalyst::Plugin::Captcha

       •   CGI::Application::Plugin::CAPTCHA

       •   Angerwhale::Controller::Captcha

   Software Using GD::SecurityImage
       If your software uses "GD::SecurityImage" for captcha generation and want to appear in
       this document, contact the author.

SUPPORT

   BUG REPORTS
       All bug reports and wishlist items must be reported via the CPAN RT system. It is
       accessible at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=GD-SecurityImage>.

   DISCUSSION FORUM
       "CPAN::Forum" is a place for discussing "CPAN" modules. It also has a "GD::SecurityImage"
       section at <http://www.cpanforum.com/dist/GD-SecurityImage>.

   RATINGS
       If you like or hate or have some suggestions about "GD::SecurityImage", you can
       comment/rate the distribution via the "CPAN Ratings" system:
       <http://cpanratings.perl.org/dist/GD-SecurityImage>.

AUTHOR

       Burak Gursoy <burak@cpan.org>.

COPYRIGHT

       Copyright 2004 - 2012 Burak Gursoy. All rights reserved.

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.10.1 or, at your option, any later version of
       Perl 5 you may have available.