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:

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

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.

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¶

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"

OTHER USE CASES¶

"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;

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

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.

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