/ 
Test-Image-0.02
River stage zero No dependents
/ Test::Image

NAME

Test::Image - test an image

SYNOPSIS

use Test::More plan => 1;
use Test::Image;

# create a new image tester
my $i = Test::Image->new(Image::Imlib2->new("foo.jpg"));
ok($i, "image ok");  
$i->size(400,300);  # (see also $i->width, $i->height)

# you can check pixels using names, rgb hex, or rgb decimal  
$i->pixel(10,10,"white");           # 10, 10 is white
$i->pixel(10,10,"ffffff");          # 10, 10 is white
$i->pixel(10,10,[255,255,255]);     # 10, 10 is white

$i->pixel_not(10,10,"white");       # 10, 10 isn't white
$i->pixel_not(10,10,"ffffff");      # 10, 10 isn't white
$i->pixel_not(10,10,[255,255,255]); # 10, 10 isn't white

# you can use multiple posibilities too
# check pixel is red, white or blue:
$i->pixel(10,10,["red", "white", "blue"]);  
$i->pixel(10,10,["ff0000", "ffffff", "0000ff"]);
$i->pixel(10,10,[[255,0,0], [255,255,255], [0,0,255]]);

# check that the pixel isn't red white or blue:
$i->pixel_not(10,10,["red", "white", "blue"]);
$i->pixel_not(10,10,["ff0000", "ffffff", "0000ff"]);
$i->pixel_not(10,10,[[255,0,0], [255,255,255], [0,0,255]]);

# row functions (or replace "row" with "col" or "column" for column tests)
# you can use multiple colours
$i->row(10, "white");       # row 11 is all white
$i->row_all(10, "white");   # row 11 is all white
$i->row_any(10, "white");   # row 11 has a white pixel
$i->row_none(10, "white");  # row 11 has no white pixels

# likewise for the whole image (again can use multiple colours)
$i->all("white");           # whole image is white
$i->any("white");           # whole image has a white pixel
$i->none("white");          # whole image has no white pixels

# finally regions (you can use _all, _any or _none too)
# check the 10x10 region starting at 40,30
$i->region(40, 30, "r10", "r10", "white");

DESCRIPTION

This modules is a Test::Builder compatible testing module for testing images.

Calling the methods of this module prints out Test Anything Protocol output designed to be processed by Test::Harness during a make test or ./Build test. This module 'plays nice' with other test modules also crafted with Test::Builder. For example, you can happily use this module in conjunction with Test::More, Test::Exception, Test::DatabaseRow, etc, and not have to worry about your test numbers getting confused.

All methods take an optional description as the last arguement. For example:

$i->width(400);                  # prints "ok 1 - image width"
$i->width(400, "1st width");     # prints "ok 2 - 1st width"

Constructing

new($image)

The constructor takes one arguement, the image you want to test. By default we only support GD::image and Image::Imlib2 objects, but you can provide further plugins for other image formats by following the PLUGINS guide below.

Image Size

There are various tests that can be used to check the magnitude of the image:

# check that fred.png is 100 by 300 pixels big
my $i = Test::Image->new(Image::Imlib2->new( "fred.png" ));
$i->size(100,300)

If you have Number::Compare installed, then you can use non absolute values, and you can use magnitudes.

# image is at least 300x200
$i->size(">=300", ">=200");

# It's a five megapixel image!
$i->total_pixels(">=5M");

See Number::Compare for more info. If you do not have Number::Compare installed, these style of tests will be automatically skipped.

width($w_pixels)

Test the width of the image

height($h_pixels)

Test the height of the image

size($w_pixels, $h_pixels)

Test the width and the height of the image at the same time

total_size($pixels)

Test the total number of pixels in the image (i.e. width x height)

Color specification

The testing system can cope with multiple definitions of color. You can use an arrayref containing the red, green and blue values (between 0 and 255:)

my $red = [255,0,0];

You can specify the value in hex if you want too:

my $red = "ff0000";
my $red = "FF0000";  # it's case insensitive
my $red = "ff0000";  # you can put a # at the start if you want

If you install the Graphics::ColorNames module from CPAN then you can use the name of the color in the "X" color scheme.

my $red = "red";

Finally you can specify more than one colour by using an array ref containing the other forms.

my $rwab = ["red", "white", "blue"];
my $rwab = ["ff0000", "ffffff", "0000ff"];
my $rwab = [[255,0,0], [255,255,255], [0,0,255]];

Checking Single Pixels

The simple pixel test can be used to check the color of a given pixel either is or isn't a particular color (or set of colors)

# check the pixel at 40, 30 is red
$i->pixel(40, 30, [255,0,0])

# check the pixel at 40, 30 is red or white
$i->pixel(40, 30, [[255,0,0], [255,255,255]])

# check the pixel at 40, 30 isn't red
$i->pixel_not(40, 30, [255,0,0])

# check the pixel at 40, 30 isn't red or white
$i->pixel_not(40, 30, [[255,0,0], [255,255,255]])

This will fail if the pixel isn't the correct color, or the pixel is outside the image.

You can also use negative numbers to indicate coordinates relative the far sides of the image in a similar manner to Perl arrays. For example:

$i->pixel(-1,-2, "red");

Is the same for a 400x300 image as:

$i->pixel(399,298, "red");

PLUGINS

This module can be extended to allow you to test arbitary image formats. To do this you need to implement a module called Test::Image::Plugin::* which supports the following methods:

new( $image )

A constructor. Return an object if you're prepared to handle the image that's passed in. Return undef if the image isn't something you'll handle (hopefully some other plugin will.)

width
height

Instance methods. These methods should return the width and height of the image.

color_at($x, $y)

Instance method should return a three element list that contains the red, green and blue value. This should return the empty list if the pixel specified is outside the image.

In order for these plugins to work you must first install Module::Pluggable from CPAN. If you're writing Test::Image plugin and distributing it on CPAN, you should add Module::Pluggable to your required modules in Makefile.PL / Build.PL

BUGS

If you don't have module compare installed and you pass a string to any of the image size routines that isn't just a plain old number then that test will be skipped if you don't have Number::Compare installed, even if that string is just junk. This is to allow this module to be compatible with future improvements to Number::Compare. You are encouraged to have Number::Compare installed when developing tests on your own system.

We should probably automatically skip named colors if you don't have Graphics::ColorNames installed. We don't yet.

Please report any further bugs you find via the CPAN RT system. http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test::Image

OTHER BUGS

British Airways doesn't have TIVO like movies like Virgin Atlantic. Or, if it does, it doesn't have it on this flight, and that's all I really care about at the momement.

In the movie "Failure To Launch" taking of your facemask while playing paintball is insanely dangerous. It also makes me want to shout lock off! when Ace is belaying. I don't find climbing accidents funny. Who's belaying the guy from Alias in that scene anyway? Despite all that, I quite enjoyed the film.

I somehow ended up with some of my sister in law's music in iTunes and now when I'm coding I sometime randomly get some Christina Aguilera.

Coding on a plane is very hard to do, as you don't have the arm room to type properly.

This said, I don't get a chance to listen to my entire Chemical Brothers collection in one go uninterrupted very often.

AUTHOR

Written by Mark Fowler, <mark@twoshortplanks.com>. Please see http://twoshortplanks.com/contact/ for details of how to contact me.

Copyright Fotango 2006-2007. All rights reserved.

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

SEE ALSO

Test::Image::GD, for an alternative way of testing GD Images.

Exporter

The Test Anything Protocol