Class ImageMagickHelper


  • public class ImageMagickHelper
    extends java.lang.Object
    A utility class that is used as an interface to run 3rd-party tool ImageMagick. ImageMagick among other things allows to compare images and this class provides means to utilize this feature.

    The ImageMagick needs to be installed independently on the system. This class provides a convenient way to run it by passing a terminal command. The command can either be specified explicitly or by a mean of environment variable MAGICK_COMPARE_ENVIRONMENT_VARIABLE.

    • Constructor Summary

      Constructors 
      Constructor Description
      ImageMagickHelper()
      Creates new instance that will rely on ImageMagick execution command defined by MAGICK_COMPARE_ENVIRONMENT_VARIABLE environment variable.
      ImageMagickHelper​(java.lang.String newCompareExec)
      Creates new instance that will rely on ImageMagick execution command defined as passed argument.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getCliExecutionCommand()
      Returns a command that is used to run the utility.
      private static long parseImageMagickProcessOutput​(java.lang.String processOutput)  
      boolean runImageMagickImageCompare​(java.lang.String outImageFilePath, java.lang.String cmpImageFilePath, java.lang.String diffImageName)
      Runs imageMagick to visually compare images and generate difference output.
      boolean runImageMagickImageCompare​(java.lang.String outImageFilePath, java.lang.String cmpImageFilePath, java.lang.String diffImageName, java.lang.String fuzzValue)
      Runs imageMagick to visually compare images with the specified fuzziness value and generate difference output.
      ImageMagickCompareResult runImageMagickImageCompareAndGetResult​(java.lang.String outImageFilePath, java.lang.String cmpImageFilePath, java.lang.String diffImageName, java.lang.String fuzzValue)
      Runs imageMagick to visually compare images with the specified fuzziness value and generate difference output.
      boolean runImageMagickImageCompareWithThreshold​(java.lang.String outImageFilePath, java.lang.String cmpImageFilePath, java.lang.String diffImageName, java.lang.String fuzzValue, long threshold)
      Runs imageMagick to visually compare images with the specified fuzziness value and given threshold and generate difference output.
      (package private) static boolean validateFuzziness​(java.lang.String fuzziness)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • MAGICK_COMPARE_ENVIRONMENT_VARIABLE

        public static final java.lang.String MAGICK_COMPARE_ENVIRONMENT_VARIABLE
        The name of the environment variable with the command to execute ImageMagic comparison operations.
        See Also:
        Constant Field Values
      • MAGICK_COMPARE_ENVIRONMENT_VARIABLE_LEGACY

        @Deprecated
        static final java.lang.String MAGICK_COMPARE_ENVIRONMENT_VARIABLE_LEGACY
        Deprecated.
        See Also:
        Constant Field Values
      • MAGICK_COMPARE_KEYWORD

        static final java.lang.String MAGICK_COMPARE_KEYWORD
        See Also:
        Constant Field Values
      • TEMP_FILE_PREFIX

        private static final java.lang.String TEMP_FILE_PREFIX
        See Also:
        Constant Field Values
      • DIFF_PIXELS_OUTPUT_REGEXP

        private static final java.lang.String DIFF_PIXELS_OUTPUT_REGEXP
        See Also:
        Constant Field Values
      • pattern

        private static final java.util.regex.Pattern pattern
      • compareExec

        private java.lang.String compareExec
    • Constructor Detail

      • ImageMagickHelper

        public ImageMagickHelper()
        Creates new instance that will rely on ImageMagick execution command defined by MAGICK_COMPARE_ENVIRONMENT_VARIABLE environment variable.
      • ImageMagickHelper

        public ImageMagickHelper​(java.lang.String newCompareExec)
        Creates new instance that will rely on ImageMagick execution command defined as passed argument.
        Parameters:
        newCompareExec - the ImageMagick execution command; if null - environment variables will be used instead
    • Method Detail

      • getCliExecutionCommand

        public java.lang.String getCliExecutionCommand()
        Returns a command that is used to run the utility. This command doesn't contain command parameters. Parameters are added on specific methods invocation.
        Returns:
        a string command
      • runImageMagickImageCompare

        public boolean runImageMagickImageCompare​(java.lang.String outImageFilePath,
                                                  java.lang.String cmpImageFilePath,
                                                  java.lang.String diffImageName)
                                           throws java.io.IOException,
                                                  java.lang.InterruptedException
        Runs imageMagick to visually compare images and generate difference output.

        Note, that this method may create temporary files.

        Parameters:
        outImageFilePath - Path to the output image file
        cmpImageFilePath - Path to the cmp image file
        diffImageName - Path to the difference output image file
        Returns:
        boolean result of comparing: true - images are visually equal
        Throws:
        java.io.IOException - if there are file's reading/writing issues
        java.lang.InterruptedException - if there is thread interruption while executing ImageMagick.
      • runImageMagickImageCompare

        public boolean runImageMagickImageCompare​(java.lang.String outImageFilePath,
                                                  java.lang.String cmpImageFilePath,
                                                  java.lang.String diffImageName,
                                                  java.lang.String fuzzValue)
                                           throws java.io.IOException,
                                                  java.lang.InterruptedException
        Runs imageMagick to visually compare images with the specified fuzziness value and generate difference output.

        Note, that this method may create temporary files.

        Parameters:
        outImageFilePath - Path to the output image file
        cmpImageFilePath - Path to the cmp image file
        diffImageName - Path to the difference output image file
        fuzzValue - String fuzziness value to compare images. Should be formatted as string with integer or decimal number. Can be null, if it is not required to use fuzziness
        Returns:
        boolean result of comparing: true - images are visually equal
        Throws:
        java.io.IOException - if there are file's reading/writing issues
        java.lang.InterruptedException - if there is thread interruption while executing ImageMagick.
      • runImageMagickImageCompareWithThreshold

        public boolean runImageMagickImageCompareWithThreshold​(java.lang.String outImageFilePath,
                                                               java.lang.String cmpImageFilePath,
                                                               java.lang.String diffImageName,
                                                               java.lang.String fuzzValue,
                                                               long threshold)
                                                        throws java.io.IOException,
                                                               java.lang.InterruptedException
        Runs imageMagick to visually compare images with the specified fuzziness value and given threshold and generate difference output.

        Note, that this method may create temporary files.

        Parameters:
        outImageFilePath - Path to the output image file
        cmpImageFilePath - Path to the cmp image file
        diffImageName - Path to the difference output image file
        fuzzValue - String fuzziness value to compare images. Should be formatted as string with integer or decimal number. Can be null, if it is not required to use fuzziness
        threshold - Long value of accepted threshold.
        Returns:
        boolean result of comparing: true - images are visually equal
        Throws:
        java.io.IOException - if there are file's reading/writing issues
        java.lang.InterruptedException - if there is thread interruption while executing ImageMagick.
      • runImageMagickImageCompareAndGetResult

        public ImageMagickCompareResult runImageMagickImageCompareAndGetResult​(java.lang.String outImageFilePath,
                                                                               java.lang.String cmpImageFilePath,
                                                                               java.lang.String diffImageName,
                                                                               java.lang.String fuzzValue)
                                                                        throws java.io.IOException,
                                                                               java.lang.InterruptedException
        Runs imageMagick to visually compare images with the specified fuzziness value and generate difference output. This method returns an object of ImageMagickCompareResult, containing comparing result information, such as boolean result value and the number of different pixels.

        Note, that this method may create temporary files.

        Parameters:
        outImageFilePath - Path to the output image file
        cmpImageFilePath - Path to the cmp image file
        diffImageName - Path to the difference output image file
        fuzzValue - String fuzziness value to compare images. Should be formatted as string with integer or decimal number. Can be null, if it is not required to use fuzziness
        Returns:
        an object of ImageMagickCompareResult. containing comparing result information.
        Throws:
        java.io.IOException - if there are file's reading/writing issues
        java.lang.InterruptedException - if there is thread interruption while executing ImageMagick.
      • validateFuzziness

        static boolean validateFuzziness​(java.lang.String fuzziness)
      • parseImageMagickProcessOutput

        private static long parseImageMagickProcessOutput​(java.lang.String processOutput)
                                                   throws java.io.IOException
        Throws:
        java.io.IOException