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

