Package com.itextpdf.io.util
Class ImageMagickHelper
- java.lang.Object
-
- com.itextpdf.io.util.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
.
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.String
compareExec
private static java.lang.String
DIFF_PIXELS_OUTPUT_REGEXP
static java.lang.String
MAGICK_COMPARE_ENVIRONMENT_VARIABLE
The name of the environment variable with the command to execute ImageMagic comparison operations.(package private) static java.lang.String
MAGICK_COMPARE_KEYWORD
private static java.util.regex.Pattern
pattern
private static java.lang.String
TEMP_FILE_PREFIX
-
Constructor Summary
Constructors Constructor Description ImageMagickHelper()
Creates new instance that will rely on ImageMagick execution command defined byMAGICK_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)
-
-
-
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_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 byMAGICK_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 filecmpImageFilePath
- Path to the cmp image filediffImageName
- 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 issuesjava.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 filecmpImageFilePath
- Path to the cmp image filediffImageName
- Path to the difference output image filefuzzValue
- 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 issuesjava.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 filecmpImageFilePath
- Path to the cmp image filediffImageName
- Path to the difference output image filefuzzValue
- 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 fuzzinessthreshold
- 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 issuesjava.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 ofImageMagickCompareResult
, 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 filecmpImageFilePath
- Path to the cmp image filediffImageName
- Path to the difference output image filefuzzValue
- 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 issuesjava.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
-
-