NAME

Imager::Test - common functions used in testing Imager

SYNOPSIS

use Imager::Test 'diff_text_with_nul';
diff_text_with_nul($test_name, $text1, $text2, @string_options);

DESCRIPTION

This is a repository of functions used in testing Imager.

Some functions will only be useful in testing Imager itself, while others should be useful in testing modules that use Imager.

No functions are exported by default.

FUNCTIONS

Test functions

is_color1($color, $grey, $comment)

Tests if the first channel of $color matches $grey.

is_color3($color, $red, $green, $blue, $comment)

Tests if $color matches the given ($red, $green, $blue)

is_color4($color, $red, $green, $blue, $alpha, $comment)

Tests if $color matches the given ($red, $green, $blue, $alpha)

is_fcolor1($fcolor, $grey, $comment)

is_fcolor1($fcolor, $grey, $epsilon, $comment)

Tests if $fcolor's first channel is within $epsilon of ($grey). For the first form $epsilon is taken as 0.001.

is_fcolor3($fcolor, $red, $green, $blue, $comment)

is_fcolor3($fcolor, $red, $green, $blue, $epsilon, $comment)

Tests if $fcolor's channels are within $epsilon of ($red, $green, $blue). For the first form $epsilon is taken as 0.001.

is_fcolor4($fcolor, $red, $green, $blue, $alpha, $comment)

is_fcolor4($fcolor, $red, $green, $blue, $alpha, $epsilon, $comment)

Tests if $fcolor's channels are within $epsilon of ($red, $green, $blue, $alpha). For the first form $epsilon is taken as 0.001.

is_image($im1, $im2, $comment)

Tests if the 2 images have the same content. Both images must be defined, have the same width, height, channels and the same color in each pixel. The color comparison is done at 8-bits per pixel. The color representation such as direct vs paletted, bits per sample are not checked. Equivalent to is_image_similar($im1, $im2, 0, $comment).

is_imaged($im, $im2, $comment)

is_imaged($im, $im2, $epsilon, $comment)

Tests if the two images have the same content at the double/sample level. $epsilon defaults to the platform DBL_EPSILON multiplied by four.

is_image_similar($im1, $im2, $maxdiff, $comment)

Tests if the 2 images have similar content. Both images must be defined, have the same width, height and channels. The sum of the squares of the differences of each sample are calculated and must be less than or equal to $maxdiff for the test to pass. The color comparison is done at 8-bits per pixel. The color representation such as direct vs paletted, bits per sample are not checked.

isnt_image($im1, $im2, $comment)

Tests that the two images are different. For regressions tests where something (like text output of "0") produced no change, but should have produced a change.

test_colorf_gpix($im, $x, $y, $expected, $epsilon, $comment)

Retrieves the pixel ($x,$y) from the low-level image $im and compares it to the floating point color $expected, with a tolerance of epsilon.

test_color_gpix($im, $x, $y, $expected, $comment)

Retrieves the pixel ($x,$y) from the low-level image $im and compares it to the floating point color $expected.

test_colorf_glin($im, $x, $y, $pels, $comment)

Retrieves the floating point pixels ($x, $y)-[$x+@$pels, $y] from the low level image $im and compares them against @$pels.

is_color_close3($color, $red, $green, $blue, $tolerance, $comment)

Tests if $color's first three channels are within $tolerance of ($red, $green, $blue).

is_arrayf($left, $right, $note)

is_arrayf($left, $right, $note, $tolerance)

Compares the length of @$left and @$right, then compares corresponding array elements for rough equality, controlled by $tolerance.

Reports a successful test if all matches, fails otherwise.

Reports any mismatches via diag().

Test suite functions

Functions that perform one or more tests, typically used to test various parts of Imager's implementation.

image_bounds_checks($im)

Attempts to write to various pixel positions outside the edge of the image to ensure that it fails in those locations.

Any new image type should pass these tests. Does 16 separate tests.

mask_tests($im, $epsilon)

Perform a standard set of mask tests on the OO image $im. Does 24 separate tests.

diff_text_with_nul($test_name, $text1, $text2, @options)

Creates 2 test images and writes $text1 to the first image and $text2 to the second image with the string() method. Each call adds 3 ok/not ok to the output of the test script.

Extra options that should be supplied include the font and either a color or channel parameter.

This was explicitly created for regression tests on #21770.

std_font_tests({ font => $font })

Perform standard font interface tests.

std_font_test_count()

The number of tests performed by std_font_tests().

extrachannel_tests($im)

Perform tests for a 3 color channel with 5 extra channel image. This is mostly intended to ensure that accessed are properly aligned between the various APIs. Especially that pixel to pixel transitions are covered by the total channels, not just the color channels.

check_vtable(im)

Given an OO image, extract the low level image and check its vtable is populated with the required entries.

std_image_tests(\%options)

Perform standard tests of images. This is currently slanted towards the getsamples() and setsamples() methods, but that will change over time.

%options can contain the following keys:

• bits - the number of bits to use when creating the images. Required.

• models - the image color models to check. Defaults to testing all of gray, graya, rgb and rgba.

plan tests => $local_tests + std_image_tests_count({ bits => $bits });
...
std_image_tests({ bits => $bits });

std_image_tests_count(\%options)

The number of tests performed by std_image_tests(). Must be supplied the same options as std_image_tests().

Tone curve functions

to_linear_srgb

to_linear_srgbf

Convert a sRGB tone curve sample into a linear sample.

to_linear_srgb() converts an 8-bit sample into a 16-bit sample.

to_linear_srgbf() converts a floating point sample into a floating point sample.

my $lin = to_linear_srgb($gam);
my $linf = to_linear_srgbf($gamf);

to_gamma_srgb

to_gamma_srgbf

Convert a linear sample into a sRGB tone curve sample.

to_gamma_srgb() converts a 16-bit sample into an 8-bit sample.

to_gamma_srgbf() converts a floating point sample into a floating point sample.

my $gam = to_gamma_srgb($lin);
my $gam = to_gamma_srgbf($lin);

Helper functions

test_image_raw()

Returns a 150x150x3 Imager::ImgRaw test image.

test_image()

Returns a 150x150x3 8-bit/sample, 3 channel OO test image. Name: basic.

test_image_rgba()

Returns a 150x150x3 8-bit/sample, 4 channel OO test image. Name: rgba.

test_image_16()

Returns a 150x150x3 16-bit/sample OO test image. Name: basic16

test_image_double()

Returns a 150x150x3 double/sample OO test image. Name: basic_double.

test_image_gray()

Returns a 150x150 single channel OO test image. Name: gray.

test_image_gray_a()

Returns a 150x150 2 channel OO test image. Name: gray_a.

test_image_gray_16()

Returns a 150x150 16-bit/sample single channel OO test image. Name: gray16.

test_image_mono()

Returns a 150x150 bilevel image that passes the is_bilevel() test. Name: mono.

test_image_pal()

Returns a 150x150 paletted OO test image. Name: pal.

test_image_named($name)

Return one of the other test images above based on name.

color_cmp($c1, $c2)

Performs an ordering of 3-channel colors (like <=>).

colorf_cmp($c1, $c2)

Performs an ordering of 3-channel floating point colors (like <=>).

AUTHOR

Tony Cook <tony@develop-help.com>