Package com.itextpdf.io.util

Class ImageMagickHelper

java.lang.Object
com.itextpdf.io.util.ImageMagickHelper
public class ImageMagickHelper extends 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.

  • Field Details

    • MAGICK_COMPARE_ENVIRONMENT_VARIABLE

      public static final String MAGICK_COMPARE_ENVIRONMENT_VARIABLE
      The name of the environment variable with the command to execute ImageMagic comparison operations.
      See Also:

  • Constructor Details

    • ImageMagickHelper

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

    • ImageMagickHelper

      public ImageMagickHelper (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 Details

    • getCliExecutionCommand

      public 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 (String outImageFilePath, String cmpImageFilePath, String diffImageName) throws IOException, 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:
      IOException - if there are file's reading/writing issues
      InterruptedException - if there is thread interruption while executing ImageMagick.

    • runImageMagickImageCompare

      public boolean runImageMagickImageCompare (String outImageFilePath, String cmpImageFilePath, String diffImageName, String fuzzValue) throws IOException, 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:
      IOException - if there are file's reading/writing issues
      InterruptedException - if there is thread interruption while executing ImageMagick.

    • runImageMagickImageCompareWithThreshold

      public boolean runImageMagickImageCompareWithThreshold (String outImageFilePath, String cmpImageFilePath, String diffImageName, String fuzzValue, long threshold) throws IOException, 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:
      IOException - if there are file's reading/writing issues
      InterruptedException - if there is thread interruption while executing ImageMagick.

    • runImageMagickImageCompareAndGetResult

      public ImageMagickCompareResult runImageMagickImageCompareAndGetResult (String outImageFilePath, String cmpImageFilePath, String diffImageName, String fuzzValue) throws IOException, 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:
      IOException - if there are file's reading/writing issues
      InterruptedException - if there is thread interruption while executing ImageMagick.