Images generated with GD
Info text at the top right.
Font is: Transformers.ttf
| GD::SecurityImage - Security image generator. |
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;
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().
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 the GD::SecurityImage::AC manpage
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.
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.
The constructor. new() method takes several arguments. These
arguments are listed below.
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.
Small, Large, MediumBold, Tiny, Giant.
The names are case-insensitive; you can pass lower-cased parameters.
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 degrees and can take values
between 0 and 360.
1 for GD and 0.6 for Image:Magick.
6.
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.
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.
Returns the random string. Must be called after 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.
$style can be one of the following (some of the styles may not work
if you are using a really old version of GD):
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.
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');
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).
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:
left or right.
up or down.
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.
info_text(). The value passed
to new() will be used instead.
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 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 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.
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.
See path bug in GD bug for usage and other information on this method.
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.
Download the distribution from a CPAN mirror near you, if you don't have the files.
All TTF samples generated with the bundled font StayPuft.ttf, unless stated otherwise. Most of the samples here can be generated with running the test suite that comes with the GD::SecurityImage distribution. However, images that are generated with random angles will indeed be a little different after you run the test suite on your system.
All random codes have a length of six (6) characters, unless stated otherwise.
So, (for example) there is no clipping in ELLIPS.
|
Images generated with GD |
|
| Standard interface. Font: gdGiantFont | Style: rect |
|
|
| Style: rect. Scrambled with random angles. | Style: circle. Scrambled with a fixed angle. |
|
|
| Style: default. Scrambled with a fixed angle. Info text at the top right. |
Style: circle. Scrambled with random angles. Font is: Transformers.ttf |
|
|
|
Images generated with Image::Magick |
|
| Style: circle. | Style: box. Scrambled with random angles. |
 |
 |
| Style: circle. Scrambled with a fixed angle. | Style: ellipse. Scrambled with a fixed angle. Info text at the top right. |
 |
 |
| Style: ec. Scrambled with random angles. Info text at the top right. |
Style: ec. Scrambled with random angles1. |
 |
 |
1: This image is generated with this code:
use GD::SecurityImage backend => 'Magick'; my($data, $mime, $rnd) = GD::SecurityImage ->new( width => 420, height => 100, ptsize => 40, lines => 20, thickness => 4, rndmax => 5, scramble => 1, send_ctobg => 1, bgcolor => '#009999', font => 'StayPuft.ttf', ) ->random('BURAK') ->create( qw/ ttf ec #0066CC #0066CC / ) ->particle(300, 500) ->out;
Images hosted by ImageShack.
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;
The generated graphic will be:
Image hosted by ImageShack.
die is called in some methods if something fails. You may need to
eval your code to catch exceptions.
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.
See the SUPPORT section if you have a bug or request to report.
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.
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.
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.
There are some issues related to wrong/incomplete compiling of libgd and old/new version conflicts.
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.
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:
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.
setThickness implemented in GD v2.07. If your GD version is smaller than that and you set thickness option, nothing will happen.
[GD] ellipseellipse() 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.
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.
the WebService::CaptchasDotNet manpage: A Perl interface to
http://captchas.net free captcha service. captchas.net
also offers audio captchas.
Authen::Captcha drop-in replacement module.
the Sledge::Plugin::Captcha manpage
the Catalyst::Plugin::Captcha manpage
CGI::Application::Plugin::CAPTCHA
the Angerwhale::Controller::Captcha manpage
If your software uses GD::SecurityImage for captcha generation and
want to appear in this document, contact the author.
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.
CPAN::Forum is a place for discussing CPAN
modules. It also has a GD::SecurityImage section at
http://www.cpanforum.com/dist/GD-SecurityImage.
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.
Burak Gursoy <burak@cpan.org>.
Copyright 2004 - 2012 Burak Gursoy. All rights reserved.
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. =cut
| GD::SecurityImage - Security image generator. |