GD::SecurityImage - Security image (captcha) generator.
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; # 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 (all 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 also:
require
require GD::SecurityImage; import GD::SecurityImage;
or:
require GD::SecurityImage; GD::SecurityImage->import;
if you don't like indirect object syntax.
If you dont import, the required modules will not be loaded and probably, you'll die().
import
die()
Beginning with v1.2, the module supports Image::Magick, but the default interface uses GD module. To enable Image::Magick support, you must call the module with the use_magick option:
Image::Magick
GD
use_magick
use GD::SecurityImage use_magick => 1;
require GD::SecurityImage; import GD::SecurityImage use_magick => 1;
require GD::SecurityImage; GD::SecurityImage->import(use_magick => 1);
The module does not export anything actually. But import loads the necessary sub modules.
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 of the image.
If you are an Authen::Captcha user, see GD::SecurityImage::AC for migration from Authen::Captcha to GD::SecurityImage.
Authen::Captcha
GD::SecurityImage
Version 1.51 and later of this module is a little smarter than the older versions. You can now use RGB and HEX values as the color parameters:
$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.
new() method takes several arguments. These arguments are listed below.
new()
The width of the image (in pixels).
The height of the image (in pixels).
Numerical value. The point size of the ttf character. Only necessarry if you want to use a ttf font in the image.
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.
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.
libgd
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.
If you want to use the default interface, set this paramater. The recognized values are Small, Large, MediumBold, Tiny, Giant. The names are case-insensitive; you can pass lower-cased parameters.
Small
Large
MediumBold
Tiny
Giant
The background color of the image.
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)
If has a true value, a frame will be added around the image. This option is enabled by default.
If set, the characters will be scrambled. If you enable this option, be sure to use a wider image, since the characters will be separeted with three spaces.
Sets the angle for scrambled 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.
angle
Unlike the GD interface, angle is in degrees and can take values between 0 and 360.
degree
0
360
Sets the line drawing width. Can take numerical values. Default values are 1 for GD and 0.6 for Image:Magick.
1
0.6
The length of the random string. Default value is 6.
6
Not necessary and will not be used if you pass your own random string.
Default character set used to create the random string is 0..9. But, if you want to use letters also, you can set this paramater. This paramater takes an array reference as the value.
0..9
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 by an object table) characters long.
Returns the random string. Must be called after random().
random()
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.
$method
normal
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):
$style
The default style. Draws horizontal, vertical and angular lines.
Draws horizontal and vertical lines
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.
lines
5
Draws circles.
Draws ellipses.
This is the combination of ellipse and circle styles. Draws both ellipses and circles.
Note: if you have a (very) 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):
$text_color
$line_color
$image->create($method, $style, [0,0,0], [200,200,200]); $image->create($method, $style, '#000000', '#c8c8c8');
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.
$density
200
70
200 * 20 = 4000
$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.
$maxdots
4
The color of the particles are the same as the color of your text (defined in create).
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).
gif
jpeg
png
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).
force
out method accepts arguments:
out
@data = $image->out(%args);
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.
out()
And with the compress parameter, you can define the compression for png and quality for jpeg:
compress
@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:
9
@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.
1..100
Compression and quality operations are disabled by default.
Depending on your usage of the module; returns the raw GD::Image object:
GD::Image
my $gd = $image->raw; print $gd->png;
or the raw Image::Magick object:
my $magick = $image->raw; $magick->Write("gif:-");
Can be usefull, if you want to modify the graphic yourself. If you want to get an image format (also see the force option in out).
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"
See the tests in the distribution. Also see the demo program "eg/demo.pl" for an Apache::Session implementation of GD::SecurityImage.
Apache::Session
Download the distribution from a CPAN mirror near you, if you don't have the files.
die is called in some methods if something fails. You may need to eval your code to catch exceptions.
die
eval
GD, Image::Magick, ImagePwd, Authen::Captcha.
GD::SecurityImage::AC: Authen::Captcha drop-in replacement module.
ImageCode Perl Module (commercial): http://www.progland.com/ImageCode.html.
ImageCode
The CAPTCHA project: http://www.captcha.net/.
A definition of CAPTCHA (From Wikipedia, the free encyclopedia): http://en.wikipedia.org/wiki/Captcha.
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, your code will probably die.
[GD] ellipse
ellipse() method added in GD 2.07.
ellipse()
If your GD version is smaller than 2.07 and you use ellipse, the default style will be returned.
ellipse
default
If your GD is smaller than 2.07 and you use ec, only the circles will be drawn.
ec
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.
QueryFontMetrics()
"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.
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():
gdbox_empty()
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.
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.
gif()
You can test if gif is working from the command line:
perl -MGD -e '$_=GD::Image->new;$_->colorAllocate(0,0,0);print$_->gif'
perl -MGD -e "$_=GD::Image->new;$_->colorAllocate(0,0,0);print$_->gif"
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.
Contact the author if you find any bugs. You can also send requests.
Burak Gürsoy, <burak@cpan.org>
Copyright 2004-2005 Burak Gürsoy. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
4 POD Errors
The following errors were encountered while parsing the POD:
Expected '=item *'
Non-ASCII character seen before =encoding in 'Gürsoy,'. Assuming CP1252
To install GD::SecurityImage, copy and paste the appropriate command in to your terminal.
cpanm
cpanm GD::SecurityImage
CPAN shell
perl -MCPAN -e shell install GD::SecurityImage
For more information on module installation, please visit the detailed CPAN module installation guide.