vispy.testing.image_tester module#

Test utilities for comparing rendered results with expected image files.

Procedure for unit-testing with images:

  1. Run unit tests at least once; this initializes a git clone of vispy/test-data in config[‘test_data_path’]. This path is ~/.vispy/test-data unless the config variable has been modified. The config file is located at vispy/vispy/util/config.py

  2. Run individual test scripts with the –vispy-audit flag:

    $ python vispy/visuals/tests/test_ellipse.py –vispy-audit

    Any failing tests will display the test results, standard image, and the differences between the two. If the test result is bad, then press (f)ail. If the test result is good, then press (p)ass and the new image will be saved to the test-data directory.

  3. After adding or changing test images, create a new commit:

    $ cd ~/.vispy/test-data $ git add … $ git commit -a

  4. Look up the most recent tag name from the test_data_tag variable in get_test_data_repo() below. Increment the tag name by 1 in the function and create a new tag in the test-data repository:

    $ git tag test-data-NNN $ git push –tags origin main

    This tag is used to ensure that each vispy commit is linked to a specific commit in the test-data repository. This makes it possible to push new commits to the test-data repository without interfering with existing tests, and also allows unit tests to continue working on older vispy versions.

    Finally, update the tag name in get_test_data_repo to the new name.

class vispy.testing.image_tester.ImageTester#

Bases: SceneCanvas

Graphical interface for auditing image comparison tests.

on_key_press(event)#
test(im1, im2, message)#
vispy.testing.image_tester.assert_image_approved(image, standard_file, message=None, **kwargs)#

Check that an image test result matches a pre-approved standard.

If the result does not match, then the user can optionally invoke a GUI to compare the images and decide whether to fail the test or save the new image as the standard.

This function will automatically clone the test-data repository into ~/.vispy/test-data. However, it is up to the user to ensure this repository is kept up to date and to commit/push new images after they are saved.

Run the test with python <test-path> –vispy-audit-tests to bring up the auditing GUI.

Parameters:
image(h, w, 4) ndarray or ‘screenshot’

The test result to check

standard_filestr

The name of the approved test image to check against. This file name is relative to the root of the vispy test-data repository and will be automatically fetched.

messagestr

A string description of the image. It is recommended to describe specific features that an auditor should look for when deciding whether to fail a test.

Extra keyword arguments are used to set the thresholds for automatic image
comparison (see ``assert_image_match()``).
vispy.testing.image_tester.assert_image_match(im1, im2, min_corr=0.9, px_threshold=50.0, px_count=None, max_px_diff=None, avg_px_diff=None, img_diff=None)#

Check that two images match.

Images that differ in shape or dtype will fail unconditionally. Further tests for similarity depend on the arguments supplied.

Parameters:
im1(h, w, 4) ndarray

Test output image

im2(h, w, 4) ndarray

Test standard image

min_corrfloat or None

Minimum allowed correlation coefficient between corresponding image values (see numpy.corrcoef)

px_thresholdfloat

Minimum value difference at which two pixels are considered different

px_countint or None

Maximum number of pixels that may differ

max_px_difffloat or None

Maximum allowed difference between pixels

avg_px_difffloat or None

Average allowed difference between pixels

img_difffloat or None

Maximum allowed summed difference between images

vispy.testing.image_tester.assert_image_reasonable(image)#

Check that an image is reasonable.

The given image is checked to not be completely black or white.

vispy.testing.image_tester.downsample(data, n, axis=0)#

Downsample by averaging points together across axis. If multiple axes are specified, runs once per axis.

vispy.testing.image_tester.get_test_data_repo()#

Return the path to a git repository with the required commit checked out.

If the repository does not exist, then it is cloned from vispy/test-data. If the repository already exists then the required commit is checked out.

vispy.testing.image_tester.git_cmd_base(path)#
vispy.testing.image_tester.git_commit_id(path, ref)#

Return the commit id of ref in the git repository at path.

vispy.testing.image_tester.git_status(path)#

Return a string listing all changes to the working tree in a git repository.

vispy.testing.image_tester.make_diff_image(im1, im2)#

Return image array showing the differences between im1 and im2.

Handles images of different shape. Alpha channels are not compared.