GD::SecurityImage(3) User Contributed Perl Documentation GD::SecurityImage(3)NAMEGD::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.70 of "GD::SecurityImage" released on
"30 April 2009".
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 paramater. 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 paramater.
This paramater 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 informations 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 paramter 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 usefull, 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
<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
<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
<http://cpanratings.perl.org/dist/GD-SecurityImage>.
AUTHOR
Burak Guersoy, <burak@cpan.org>
COPYRIGHT
Copyright 2004-2008 Burak Guersoy. 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.8.8 or, at
your option, any later version of Perl 5 you may have available.
perl v5.14.1 2011-06-28 GD::SecurityImage(3)
