/ 
GD-SecurityImage-1.3
River stage two • 12 direct dependents • 16 total dependents
/ GD::SecurityImage

NAME

GD::SecurityImage - Create a security image with a random string on it.

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;

# use external ttf font
my $image = GD::SecurityImage->new(width  => 100,
                                   height => 40,
                                   lines  => 10,
                                   font   => "/absolute/path/to/your.ttf");
   $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 usefull.

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

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

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:

use GD::SecurityImage use_magick => 1;

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

require GD::SecurityImage;
import GD::SecurityImage use_magick => 1;

or:

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

if you don't like indirect object syntax.

If you dont import, the required modules will not be loaded and probably, you'll die().

The module does not export anything actually. But import loads the necessary sub modules.

NOTE: 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.

DESCRIPTION

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

METHODS

new

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. Not necessarry unless you want to use ttf fonts 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.

rndmax

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

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

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.

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 showed on the background and the lines will pass over it. (send_ctobg = send code to background)

Do not use with the box style.

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 by a class variable) 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.

The last two arguments are the colors used in the image (text and line color -- respectively) and they are passed as a 3-element (red, green and blue) arrayref.

$image->create($method, $style, [0,0,0], [200,200,200]);

particle

Must be called after create.

Adds random dots to the image. They'll cover all the surface. Accepts two parameters; the density (number) of the particles.

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

Default value of $density is dependent on your image' s width or height. 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).

$maxdots defines the maximum number of dots near a pixel. 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).

out

This method finally returns the created image, the mime type of the image and the random number generated. Older versions of GD only supports gif types, while new versions support jpeg and png.

The returned mime type is either gif or jpeg for GD and gif for Image::Magick.

out accepts arguments:

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

currently, you can only set output format with the force key:

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

Currently, you can not define compression values for the formats that support it (eg: jpeg, png), but you can use raw method instead of out (for a direct communication with the graphic library).

raw

Returns the raw GD::Image object:

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

or the raw Image::Magick object:

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

Can be usefull, if you want to modify the graphic yourself, or want to use another output format like png.

CAVEAT EMPTOR

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

SEE ALSO

GD, ImagePwd.

EXAMPLES

TTF example

#!/usr/bin/perl -w
use strict;
use CGI;
use GD::SecurityImage;

my $cgi = CGI->new;

my $ttf = "/absolute/path/to/your.ttf";

my $image = GD::SecurityImage->new(
               width    => 90,
               height   => 35,
               ptsize   => 15,
               lines    => 10,
               rndmax   => 6,
               rnd_data => [0..9, 'A'..'Z'],
               font     => $ttf,
               bgcolor  => [115, 255, 255],
);

$image->random;
$image->create(ttf => 'rect', [10,10,10], [210,210,50]);

my($image_data, $mime_type, $random_string) = $image->out;

print $cgi->header(-type => "image/$mime_type");
print $image_data;

Normal example

#!/usr/bin/perl -w
use strict;
use CGI;
use GD::SecurityImage;

my $cgi = CGI->new;

my $image = GD::SecurityImage->new(
               width    => 90,
               height   => 35,
               ptsize   => 15,
               lines    => 10,
               gd_font  => 'giant',
               bgcolor  => [115, 255, 255],
);

$image->random('12GH88');
$image->create(normal => 'rect', [10,10,10], [210,210,50]);

my($image_data, $mime_type, $random_string) = $image->out;

print $cgi->header(-type => "image/$mime_type");
print $image_data;

Image::Magick example

#!/usr/bin/perl -w
use strict;
use CGI;
use GD::SecurityImage use_magick => 1;

my $cgi = CGI->new;

my $ttf = "/absolute/path/to/your.ttf";

my $image = GD::SecurityImage->new(
               width    => 90,
               height   => 35,
               ptsize   => 15,
               lines    => 10,
               font     => $ttf,
               bgcolor  => [115, 255, 255],
);

$image->random('BLAH');
$image->create(ttf => 'ec', [10,10,10], [210,210,50]);

my($image_data, $mime_type, $random_string) = $image->out;

print $cgi->header(-type => "image/$mime_type");
print $image_data;

require example

#!/usr/bin/perl -w
use strict;
use CGI;
require GD::SecurityImage;
import  GD::SecurityImage use_magick => 1;

my $cgi = CGI->new;

my $ttf = "/absolute/path/to/your.ttf";

my $image = GD::SecurityImage->new(
               width    => 90,
               height   => 35,
               ptsize   => 15,
               lines    => 10,
               font     => $ttf,
               bgcolor  => [115, 255, 255],
);

$image->random('FOOBAR');
$image->create(ttf => 'ec', [10,10,10], [210,210,50]);

my($image_data, $mime_type, $random_string) = $image->out;

print $cgi->header(-type => "image/$mime_type");
print $image_data;

ERROR HANDLING

Currently, the module does not check the return values of GD's and Image::Magick' s methods. So, if an error occurs, you may just get an empty image instead of die()ing.

BUGS

Contact the author if you find any. You can also send requests.

AUTHOR

Burak Gürsoy, <burak@cpan.org>

COPYRIGHT

Copyright 2004 Burak Gürsoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 561:

Non-ASCII character seen before =encoding in 'Gürsoy,'. Assuming CP1252