obspy.core.util.testing.ImageComparison

class ImageComparison(image_path, image_name, reltol=1, adjust_tolerance=True, plt_close_all_enter=True, plt_close_all_exit=True, style=None, no_uploads=False, *args, **kwargs)[source]

Bases: obspy.core.util.base.NamedTemporaryFile

Handles the comparison against a baseline image in an image test.

Note

Baseline images are created using matplotlib version 1.3.1.

Parameters
  • image_path (str) – Path to directory where the baseline image is located

  • image_name (str) – Filename (with suffix, without directory path) of the baseline image

  • reltol (float, optional) – Multiplier that is applied to the default tolerance value (i.e. 10 means a 10 times harder to pass test tolerance).

  • adjust_tolerance (bool, optional) – Adjust the tolerance based on the matplotlib version. Can optionally be turned off to simply compare two images.

  • plt_close_all_enter (bool) – Whether to close all open figures when entering context (matplotlib.pyplot.close() with “all” as first argument.

  • plt_close_all_exit (bool) – Whether to call matplotlib.pyplot.close() with “all” as first argument (close all figures) or no arguments (close active figure). Has no effect if plt_close=False.

  • style (str) – The Matplotlib style to use to generate the figure. When using matplotlib 1.5 or newer, the default will be 'classic' to ensure compatibility with older releases. On older releases, the default will leave the style as is. You may wish to set it to 'default' to enable the new style from Matplotlib 2.0, or some alternate style, which will work back to Matplotlib 1.4.0.

  • no_uploads (bool) – If set to True no uploads to imgur are attempted, no matter what (e.g. any options to obspy-runtests that would normally cause an upload attempt). This can be used to forcibly deactivate upload attempts in image tests that are expected to fail.

The class should be used with Python’s “with” statement. When setting up, the matplotlib rcdefaults are set to ensure consistent image testing. After the plotting is completed, the ImageComparison.compare() method is called automatically at the end of the “with” block, comparing against the previously specified baseline image. This raises an exception (if the test fails) with the message string from matplotlib.testing.compare.compare_images(). Afterwards all temporary files are deleted automatically.

Note

If images created during the testrun should be kept after the test, set environment variable OBSPY_KEEP_IMAGES to any value before executing the test (e.g. with $ OBSPY_KEEP_IMAGES= obspy-runtests or $ OBSPY_KEEP_IMAGES= python test_sometest.py). For obspy-runtests the option “–keep-images” can also be used instead of setting an environment variable. Created images and diffs for failing tests are then stored in a subfolder “testrun” under the baseline image’s directory. To only keep failed images and the corresponding diff image, additionally set environment variable OBSPY_KEEP_ONLY_FAILED_IMAGES to any value before executing the test.

Example

>>> from obspy import read
>>> with ImageComparison("/my/baseline/folder", 'plot.png') as ic:
...     st = read()  # doctest: +SKIP
...     st.plot(outfile=ic.name)  # doctest: +SKIP
...     # image is compared against baseline image automatically

Attributes

__abstractmethods__

__dict__

__doc__

__module__

closed

Public Methods

close

Flush and close the IO object.

compare

Run a custom version of matplotlib.testing.compare.compare_images() and raise an unittest.TestCase.failureException with the message string given by matplotlib if the comparison exceeds the allowed tolerance.

detach

Disconnect this buffer from its underlying raw stream and return it.

fileno

Returns underlying file descriptor if one exists.

flush

Flush write buffers, if applicable.

isatty

Return whether this is an ‘interactive’ stream.

read

Read and return up to n bytes.

read1

Read and return up to n bytes, with at most one read() call to the underlying raw stream.

readable

Return whether object was opened for reading.

readinto

readinto1

readline

Read and return a line from the stream.

readlines

Return a list of lines from the stream.

seek

Change stream position.

seekable

Return whether object supports random access.

tell

Return current stream position.

truncate

Truncate file to size bytes.

writable

Return whether object was opened for writing.

write

Write the given buffer to the IO stream.

writelines

Private Methods

Warning

Private methods are mainly for internal/developer use and their API might change without notice.

_checkClosed

_checkReadable

_checkSeekable

_checkWritable

_copy_tempfiles

Copies created images from tempfiles to a subfolder of baseline images.

_get_final_filenames

Helper function returning the :return:

_upload_images

Uploads images to imgur unless explicitly deactivated with option no_uploads (to speed up tests that are expected to fail).

Special Methods

__dir__

Default dir() implementation.

__enter__

Set matplotlib defaults.

__exit__

Remove tempfiles and store created images if OBSPY_KEEP_IMAGES environment variable is set.

__format__

Default object formatter.

__init__

Initialize self.

__init_subclass__

This method is called when a class is subclassed.

__new__

Create and return a new object.

__reduce__

Helper for pickle.

__reduce_ex__

Helper for pickle.

__sizeof__

Size of object in memory, in bytes.

__subclasshook__

Abstract classes can override this to customize issubclass().