code: def compare_images(expected, actual, tol, in_decorator=False):
      """
      Compare two "image" files checking differences within a tolerance.
  
      The two given filenames may point to files which are convertible to
      PNG via the `.converter` dictionary. The underlying RMS is calculated
      with the `.calculate_rms` function.
  
      Parameters
      ----------
      expected : str
          The filename of the expected image.
      actual :str
          The filename of the actual image.
      tol : float
          The tolerance (a color value difference, where 255 is the
          maximal difference).  The test fails if the average pixel
          difference is greater than this value.
      in_decorator : bool
          If called from image_comparison decorator, this should be
          True. (default=False)
  
      Examples
      --------
      img1 = "./baseline/plot.png"
      img2 = "./output/plot.png"
      compare_images( img1, img2, 0.001 ):
  
      """
      if not os.path.exists(actual):
          raise Exception("Output image %s does not exist." % actual)
  
      if os.stat(actual).st_size == 0:
          raise Exception("Output image file %s is empty." % actual)
  
      # Convert the image to png
      extension = expected.split(".")[-1]
  
      if not os.path.exists(expected):
          raise IOError("Baseline image %r does not exist." % expected)
  
      if extension != "png":
          actual = convert(actual, False)
          expected = convert(expected, True)
  
      # open the image files and remove the alpha channel (if it exists)
      expectedImage = _png.read_png_int(expected)
      actualImage = _png.read_png_int(actual)
      expectedImage = expectedImage[:, :, :3]
      actualImage = actualImage[:, :, :3]
  
      actualImage, expectedImage = crop_to_same(
          actual, actualImage, expected, expectedImage
      )
  
      diff_image = make_test_filename(actual, "failed-diff")
  
      if tol <= 0.0:
          if np.array_equal(expectedImage, actualImage):
              return None
  
      # convert to signed integers, so that the images can be subtracted without
      # overflow
      expectedImage = expectedImage.astype(np.int16)
      actualImage = actualImage.astype(np.int16)
  
      rms = calculate_rms(expectedImage, actualImage)
  
      if rms <= tol:
          return None
  
      save_diff_image(expected, actual, diff_image)
  
      results = dict(
          rms=rms,
          expected=str(expected),
          actual=str(actual),
          diff=str(diff_image),
          tol=tol,
      )
  
      if not in_decorator:
          # Then the results should be a string suitable for stdout.
          template = [
              "Error: Image files did not match.",
              "RMS Value: {rms}",
              "Expected:  \n    {expected}",
              "Actual:    \n    {actual}",
              "Difference:\n    {diff}",
              "Tolerance: \n    {tol}",
          ]
          results = "\n  ".join(
              [line.format(**results) for line in template]
          )
      return results
  
imports: from __future__ import absolute_import, division, print_function
  import six
  import atexit
  import functools
  import hashlib
  import itertools
  import os
  import re
  import shutil
  import sys
  from tempfile import TemporaryFile
  import numpy
  import matplotlib
  from matplotlib.compat import subprocess
  from matplotlib.testing.exceptions import ImageComparisonFailure
  from matplotlib import _png
  from matplotlib import _get_cachedir
  from matplotlib import cbook
label_desc: Use image node_id 13 for calling a global function with example usage: compare_images(expected, actual, tol, in_decorator) and returns: results, None, None