This class provides means to compare two PDF files both by content and visually and gives the report on their differences. More...

Classes
class	CompareResult
	Class containing results of the comparison of two documents. More...

class	CompareToolExecutionException
	Exceptions thrown when errors occur during generation and comparison of images obtained on the basis of pdf files. More...

Public Member Functions
virtual CompareTool.CompareResult	CompareByCatalog (PdfDocument outDocument, PdfDocument cmpDocument)
	Compares two PDF documents by content starting from Catalog dictionary and then recursively comparing corresponding objects which are referenced from it. More...

virtual iText.Kernel.Utils.CompareTool	DisableCachedPagesComparison ()
	Disables the default logic of pages comparison. More...

virtual iText.Kernel.Utils.CompareTool	SetCompareByContentErrorsLimit (int compareByContentMaxErrorCount)
	Sets the maximum errors count which will be returned as the result of the comparison. More...

virtual iText.Kernel.Utils.CompareTool	SetGenerateCompareByContentXmlReport (bool generateCompareByContentXmlReport)
	Enables or disables the generation of the comparison report in the form of an xml document. More...

virtual void	SetEventCountingMetaInfo (IMetaInfo metaInfo)
	Sets iText.Commons.Actions.Contexts.IMetaInfo info that will be used for both read and written documents creation. More...

virtual iText.Kernel.Utils.CompareTool	EnableEncryptionCompare ()
	Enables the comparison of the encryption properties of the documents. More...

virtual ReaderProperties	GetOutReaderProperties ()
	Gets iText.Kernel.Pdf.ReaderProperties to be passed later to the iText.Kernel.Pdf.PdfReader of the output document. More...

virtual ReaderProperties	GetCmpReaderProperties ()
	Gets iText.Kernel.Pdf.ReaderProperties to be passed later to the iText.Kernel.Pdf.PdfReader of the cmp document. More...

virtual String	CompareVisually (String outPdf, String cmpPdf, String outPath, String differenceImagePrefix)
	Compares two documents visually. More...

virtual String	CompareVisually (String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, IDictionary< int, IList< Rectangle >> ignoredAreas)
	Compares two documents visually. More...

virtual String	CompareByContent (String outPdf, String cmpPdf, String outPath)
	Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. More...

virtual String	CompareByContent (String outPdf, String cmpPdf, String outPath, String differenceImagePrefix)
	Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. More...

virtual String	CompareByContent (String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, byte[] outPass, byte[] cmpPass)
	This method overload is used to compare two encrypted PDF documents. More...

virtual String	CompareByContent (String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, IDictionary< int, IList< Rectangle >> ignoredAreas)
	Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. More...

virtual String	CompareByContent (String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, IDictionary< int, IList< Rectangle >> ignoredAreas, byte[] outPass, byte[] cmpPass)
	This method overload is used to compare two encrypted PDF documents. More...

virtual bool	CompareDictionaries (PdfDictionary outDict, PdfDictionary cmpDict)
	Simple method that compares two given PdfDictionaries by content. More...

virtual CompareTool.CompareResult	CompareDictionariesStructure (PdfDictionary outDict, PdfDictionary cmpDict)
	Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. More...

virtual CompareTool.CompareResult	CompareDictionariesStructure (PdfDictionary outDict, PdfDictionary cmpDict, ICollection< PdfName > excludedKeys)
	Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. More...

virtual CompareTool.CompareResult	CompareStreamsStructure (PdfStream outStream, PdfStream cmpStream)
	Compares structures of two corresponding streams from out and cmp PDF documents. More...

virtual bool	CompareStreams (PdfStream outStream, PdfStream cmpStream)
	Simple method that compares two given PdfStreams by content. More...

virtual bool	CompareArrays (PdfArray outArray, PdfArray cmpArray)
	Simple method that compares two given PdfArrays by content. More...

virtual bool	CompareNames (PdfName outName, PdfName cmpName)
	Simple method that compares two given PdfNames. More...

virtual bool	CompareNumbers (PdfNumber outNumber, PdfNumber cmpNumber)
	Simple method that compares two given PdfNumbers. More...

virtual bool	CompareStrings (PdfString outString, PdfString cmpString)
	Simple method that compares two given PdfStrings. More...

virtual bool	CompareBooleans (PdfBoolean outBoolean, PdfBoolean cmpBoolean)
	Simple method that compares two given PdfBooleans. More...

virtual String	CompareXmp (String outPdf, String cmpPdf)
	Compares xmp metadata of the two given PDF documents. More...

virtual String	CompareXmp (String outPdf, String cmpPdf, bool ignoreDateAndProducerProperties)
	Compares xmp metadata of the two given PDF documents. More...

virtual bool	CompareXmls (byte[] xml1, byte[] xml2)
	Utility method that provides simple comparison of the two xml files stored in byte arrays. More...

virtual bool	CompareXmls (String outXmlFile, String cmpXmlFile)
	Utility method that provides simple comparison of the two xml files. More...

virtual String	CompareDocumentInfo (String outPdf, String cmpPdf, byte[] outPass, byte[] cmpPass)
	Compares document info dictionaries of two pdf documents. More...

virtual String	CompareDocumentInfo (String outPdf, String cmpPdf)
	Compares document info dictionaries of two pdf documents. More...

virtual String	CompareLinkAnnotations (String outPdf, String cmpPdf)
	Checks if two documents have identical link annotations on corresponding pages. More...

virtual String	CompareTagStructures (String outPdf, String cmpPdf)
	Compares tag structures of the two PDF documents. More...

Detailed Description

This class provides means to compare two PDF files both by content and visually and gives the report on their differences.

For visual comparison it uses external tools: Ghostscript and ImageMagick, which should be installed on your machine. To allow CompareTool to use them, you need to pass either java properties or environment variables with names "ITEXT_GS_EXEC" and "ITEXT_MAGICK_COMPARE_EXEC", which would contain the commands to execute the Ghostscript and ImageMagick tools.

CompareTool class was mainly designed for the testing purposes of iText in order to ensure that the same code produces the same PDF document. For this reason you will often encounter such parameter names as "outDoc" and "cmpDoc" which stand for output document and document-for-comparison. The first one is viewed as the current result, and the second one is referred as normal or ideal result. OutDoc is compared to the ideal cmpDoc. Therefore all reports of the comparison are in the form: "Expected ..., but was ...". This should be interpreted in the following way: "expected" part stands for the content of the cmpDoc and "but was" part stands for the content of the outDoc.

Member Function Documentation

◆ CompareArrays()

virtual bool iText.Kernel.Utils.CompareTool.CompareArrays	(	PdfArray	outArray,
		PdfArray	cmpArray
	)

inlinevirtual

Simple method that compares two given PdfArrays by content.

Simple method that compares two given PdfArrays by content. This is "deep" comparing, which means that all nested objects are also compared by content.

Parameters

outArray	array to compare.
cmpArray	array to compare.

Returns: true if arrays are equal by content, otherwise false.

◆ CompareBooleans()

virtual bool iText.Kernel.Utils.CompareTool.CompareBooleans	(	PdfBoolean	outBoolean,
		PdfBoolean	cmpBoolean
	)

inlinevirtual

Simple method that compares two given PdfBooleans.

Parameters

outBoolean	boolean to compare.
cmpBoolean	boolean to compare.

Returns: true if booleans are equal, otherwise false.

◆ CompareByCatalog()

virtual CompareTool.CompareResult iText.Kernel.Utils.CompareTool.CompareByCatalog	(	PdfDocument	outDocument,
		PdfDocument	cmpDocument
	)

inlinevirtual

Compares two PDF documents by content starting from Catalog dictionary and then recursively comparing corresponding objects which are referenced from it.

Compares two PDF documents by content starting from Catalog dictionary and then recursively comparing corresponding objects which are referenced from it. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

The main difference between this method and the CompareByContent(System.String, System.String, System.String, System.String) methods is the return value. This method returns a CompareResult class instance, which could be used in code, whilst compareByContent methods in case of the differences simply return String value, which could only be printed. Also, keep in mind that this method doesn't perform visual comparison of the documents.

For more explanations about what outDoc and cmpDoc are see last paragraph of the CompareTool class description.

Parameters

outDocument	a iText.Kernel.Pdf.PdfDocument corresponding to the output file, which is to be compared with cmp-file.
cmpDocument	a iText.Kernel.Pdf.PdfDocument corresponding to the cmp-file, which is to be compared with output file.

Returns: the report on comparison of two files in the form of the custom class CompareResult instance.

See also: CompareResult

◆ CompareByContent() [1/5]

virtual String iText.Kernel.Utils.CompareTool.CompareByContent	(	String	outPdf,
		String	cmpPdf,
		String	outPath
	)

inlinevirtual

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

When comparison by content is finished, if any differences were found, visual comparison is automatically started. For this overload, differenceImagePrefix value is generated using diff_outPdfFileName_ format.

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.

Returns: string containing text report on the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

See also: CompareVisually(System.String, System.String, System.String, System.String)

◆ CompareByContent() [2/5]

virtual String iText.Kernel.Utils.CompareTool.CompareByContent	(	String	outPdf,
		String	cmpPdf,
		String	outPath,
		String	differenceImagePrefix
	)

inlinevirtual

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

When comparison by content is finished, if any differences were found, visual comparison is automatically started.

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.
differenceImagePrefix	file name prefix for image files with marked visual differences if there are any; if it's set to null the prefix defaults to diff_outPdfFileName_ format.

Returns: string containing text report on the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

See also: CompareVisually(System.String, System.String, System.String, System.String)

◆ CompareByContent() [3/5]

virtual String iText.Kernel.Utils.CompareTool.CompareByContent	(	String	outPdf,
		String	cmpPdf,
		String	outPath,
		String	differenceImagePrefix,
		byte[]	outPass,
		byte[]	cmpPass
	)

inlinevirtual

This method overload is used to compare two encrypted PDF documents.

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

When comparison by content is finished, if any differences were found, visual comparison is automatically started. For more info see CompareVisually(System.String, System.String, System.String, System.String).

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.
differenceImagePrefix	file name prefix for image files with marked visual differences if there is any; if it's set to null the prefix defaults to diff_outPdfFileName_ format.
outPass	password for the encrypted document specified by the outPdf absolute path.
cmpPass	password for the encrypted document specified by the cmpPdf absolute path.

Returns: string containing text report on the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

See also: CompareVisually(System.String, System.String, System.String, System.String)

◆ CompareByContent() [4/5]

virtual String iText.Kernel.Utils.CompareTool.CompareByContent	(	String	outPdf,
		String	cmpPdf,
		String	outPath,
		String	differenceImagePrefix,
		IDictionary< int, IList< Rectangle >>	ignoredAreas
	)

inlinevirtual

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

When comparison by content is finished, if any differences were found, visual comparison is automatically started.

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.
differenceImagePrefix	file name prefix for image files with marked visual differences if there are any; if it's set to null the prefix defaults to diff_outPdfFileName_ format.
ignoredAreas	a map with one-based page numbers as keys and lists of ignored rectangles as values.

Returns: string containing text report on the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

See also: CompareVisually(System.String, System.String, System.String, System.String)

◆ CompareByContent() [5/5]

virtual String iText.Kernel.Utils.CompareTool.CompareByContent	(	String	outPdf,
		String	cmpPdf,
		String	outPath,
		String	differenceImagePrefix,
		IDictionary< int, IList< Rectangle >>	ignoredAreas,
		byte[]	outPass,
		byte[]	cmpPass
	)

inlinevirtual

This method overload is used to compare two encrypted PDF documents.

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

When comparison by content is finished, if any differences were found, visual comparison is automatically started.

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.
differenceImagePrefix	file name prefix for image files with marked visual differences if there are any; if it's set to null the prefix defaults to diff_outPdfFileName_ format.
ignoredAreas	a map with one-based page numbers as keys and lists of ignored rectangles as values.
outPass	password for the encrypted document specified by the outPdf absolute path.
cmpPass	password for the encrypted document specified by the cmpPdf absolute path.

Returns: string containing text report on the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

See also: CompareVisually(System.String, System.String, System.String, System.String)

◆ CompareDictionaries()

virtual bool iText.Kernel.Utils.CompareTool.CompareDictionaries	(	PdfDictionary	outDict,
		PdfDictionary	cmpDict
	)

inlinevirtual

Simple method that compares two given PdfDictionaries by content.

Simple method that compares two given PdfDictionaries by content. This is "deep" comparing, which means that all nested objects are also compared by content.

Parameters

outDict	dictionary to compare.
cmpDict	dictionary to compare.

Returns: true if dictionaries are equal by content, otherwise false.

◆ CompareDictionariesStructure() [1/2]

virtual CompareTool.CompareResult iText.Kernel.Utils.CompareTool.CompareDictionariesStructure	(	PdfDictionary	outDict,
		PdfDictionary	cmpDict
	)

inlinevirtual

Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents.

Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Both out and cmp iText.Kernel.Pdf.PdfDictionary shall have indirect references.

By default page dictionaries are excluded from the comparison when met and are instead compared in a special manner, simply comparing their page numbers. This behavior can be disabled by calling DisableCachedPagesComparison().

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outDict	an indirect iText.Kernel.Pdf.PdfDictionary from the output file, which is to be compared to cmp-file dictionary.
cmpDict	an indirect iText.Kernel.Pdf.PdfDictionary from the cmp-file file, which is to be compared to output file dictionary.

Returns

CompareResult instance containing differences between the two dictionaries, or null if dictionaries are equal.

◆ CompareDictionariesStructure() [2/2]

virtual CompareTool.CompareResult iText.Kernel.Utils.CompareTool.CompareDictionariesStructure	(	PdfDictionary	outDict,
		PdfDictionary	cmpDict,
		ICollection< PdfName >	excludedKeys
	)

inlinevirtual

Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents.

Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Both out and cmp iText.Kernel.Pdf.PdfDictionary shall have indirect references.

By default page dictionaries are excluded from the comparison when met and are instead compared in a special manner, simply comparing their page numbers. This behavior can be disabled by calling DisableCachedPagesComparison().

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outDict	an indirect iText.Kernel.Pdf.PdfDictionary from the output file, which is to be compared to cmp-file dictionary.
cmpDict	an indirect iText.Kernel.Pdf.PdfDictionary from the cmp-file file, which is to be compared to output file dictionary.
excludedKeys	a Java.Util.Set of names that designate entries from outDict and cmpDict dictionaries which are to be skipped during comparison.

Returns

CompareResult instance containing differences between the two dictionaries, or null if dictionaries are equal.

◆ CompareDocumentInfo() [1/2]

virtual String iText.Kernel.Utils.CompareTool.CompareDocumentInfo	(	String	outPdf,
		String	cmpPdf
	)

inlinevirtual

Compares document info dictionaries of two pdf documents.

Parameters

outPdf	the absolute path to the output file, which info is to be compared to cmp-file info.
cmpPdf	the absolute path to the cmp-file, which info is to be compared to output file info.

Returns: text report on the differences in documents infos.

◆ CompareDocumentInfo() [2/2]

virtual String iText.Kernel.Utils.CompareTool.CompareDocumentInfo	(	String	outPdf,
		String	cmpPdf,
		byte[]	outPass,
		byte[]	cmpPass
	)

inlinevirtual

Compares document info dictionaries of two pdf documents.

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters.

Parameters

outPdf	the absolute path to the output file, which info is to be compared to cmp-file info.
cmpPdf	the absolute path to the cmp-file, which info is to be compared to output file info.
outPass	password for the encrypted document specified by the outPdf absolute path.
cmpPass	password for the encrypted document specified by the cmpPdf absolute path.

Returns: text report on the differences in documents infos.

◆ CompareLinkAnnotations()

virtual String iText.Kernel.Utils.CompareTool.CompareLinkAnnotations	(	String	outPdf,
		String	cmpPdf
	)

inlinevirtual

Checks if two documents have identical link annotations on corresponding pages.

Parameters

outPdf	the absolute path to the output file, which links are to be compared to cmp-file links.
cmpPdf	the absolute path to the cmp-file, which links are to be compared to output file links.

Returns: text report on the differences in documents links.

◆ CompareNames()

virtual bool iText.Kernel.Utils.CompareTool.CompareNames	(	PdfName	outName,
		PdfName	cmpName
	)

inlinevirtual

Simple method that compares two given PdfNames.

Parameters

outName	name to compare.
cmpName	name to compare.

Returns: true if names are equal, otherwise false.

◆ CompareNumbers()

virtual bool iText.Kernel.Utils.CompareTool.CompareNumbers	(	PdfNumber	outNumber,
		PdfNumber	cmpNumber
	)

inlinevirtual

Simple method that compares two given PdfNumbers.

Parameters

outNumber	number to compare.
cmpNumber	number to compare.

Returns: true if numbers are equal, otherwise false.

◆ CompareStreams()

virtual bool iText.Kernel.Utils.CompareTool.CompareStreams	(	PdfStream	outStream,
		PdfStream	cmpStream
	)

inlinevirtual

Simple method that compares two given PdfStreams by content.

Simple method that compares two given PdfStreams by content. This is "deep" comparing, which means that all nested objects are also compared by content.

Parameters

outStream	stream to compare.
cmpStream	stream to compare.

Returns: true if stream are equal by content, otherwise false.

◆ CompareStreamsStructure()

virtual CompareTool.CompareResult iText.Kernel.Utils.CompareTool.CompareStreamsStructure	(	PdfStream	outStream,
		PdfStream	cmpStream
	)

inlinevirtual

Compares structures of two corresponding streams from out and cmp PDF documents.

Compares structures of two corresponding streams from out and cmp PDF documents. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

For more explanations about what outPdf and cmpPdf are see last paragraph of the CompareTool class description.

Parameters

outStream	a iText.Kernel.Pdf.PdfStream from the output file, which is to be compared to cmp-file stream.
cmpStream	a iText.Kernel.Pdf.PdfStream from the cmp-file file, which is to be compared to output file stream.

Returns

CompareResult instance containing differences between the two streams, or null if streams are equal.

◆ CompareStrings()

virtual bool iText.Kernel.Utils.CompareTool.CompareStrings	(	PdfString	outString,
		PdfString	cmpString
	)

inlinevirtual

Simple method that compares two given PdfStrings.

Parameters

outString	string to compare.
cmpString	string to compare.

Returns: true if strings are equal, otherwise false.

◆ CompareTagStructures()

virtual String iText.Kernel.Utils.CompareTool.CompareTagStructures	(	String	outPdf,
		String	cmpPdf
	)

inlinevirtual

Compares tag structures of the two PDF documents.

This method creates xml files in the same folder with outPdf file. These xml files contain documents tag structures converted into the xml structure. These xml files are compared if they are equal.

Parameters

outPdf	the absolute path to the output file, which tags are to be compared to cmp-file tags.
cmpPdf	the absolute path to the cmp-file, which tags are to be compared to output file tags.

Returns: text report of the differences in documents tags.

◆ CompareVisually() [1/2]

virtual String iText.Kernel.Utils.CompareTool.CompareVisually	(	String	outPdf,
		String	cmpPdf,
		String	outPath,
		String	differenceImagePrefix
	)

inlinevirtual

Compares two documents visually.

Compares two documents visually. For the comparison two external tools are used: Ghostscript and ImageMagick. For more info about needed configuration for visual comparison process see CompareTool class description.

Note, that this method uses iText.IO.Util.ImageMagickHelper and iText.IO.Util.GhostscriptHelper classes and therefore may create temporary files and directories.

During comparison for every page of the two documents an image file will be created in the folder specified by outPath parameter. Then those page images will be compared and if there are any differences for some pages, another image file will be created with marked differences on it.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.
differenceImagePrefix	file name prefix for image files with marked differences if there is any.

Returns: string containing list of the pages that are visually different, or null if there are no visual differences.

◆ CompareVisually() [2/2]

virtual String iText.Kernel.Utils.CompareTool.CompareVisually	(	String	outPdf,
		String	cmpPdf,
		String	outPath,
		String	differenceImagePrefix,
		IDictionary< int, IList< Rectangle >>	ignoredAreas
	)

inlinevirtual

Compares two documents visually.

Compares two documents visually. For the comparison two external tools are used: Ghostscript and ImageMagick. For more info about needed configuration for visual comparison process see CompareTool class description.

Note, that this method uses iText.IO.Util.ImageMagickHelper and iText.IO.Util.GhostscriptHelper classes and therefore may create temporary files and directories.

During comparison for every page of two documents an image file will be created in the folder specified by outPath parameter. Then those page images will be compared and if there are any differences for some pages, another image file will be created with marked differences on it.

It is possible to ignore certain areas of the document pages during visual comparison. This is useful for example in case if documents should be the same except certain page area with date on it. In this case, in the folder specified by the outPath, new pdf documents will be created with the black rectangles at the specified ignored areas, and visual comparison will be performed on these new documents.

Parameters

outPdf	the absolute path to the output file, which is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which is to be compared to output file.
outPath	the absolute path to the folder, which will be used to store image files for visual comparison.
differenceImagePrefix	file name prefix for image files with marked differences if there is any.
ignoredAreas	a map with one-based page numbers as keys and lists of ignored rectangles as values.

Returns: string containing list of the pages that are visually different, or null if there are no visual differences.

◆ CompareXmls() [1/2]

virtual bool iText.Kernel.Utils.CompareTool.CompareXmls	(	byte[]	xml1,
		byte[]	xml2
	)

inlinevirtual

Utility method that provides simple comparison of the two xml files stored in byte arrays.

Parameters

xml1	first xml file data to compare.
xml2	second xml file data to compare.

Returns: true if xml structures are identical, false otherwise.

◆ CompareXmls() [2/2]

virtual bool iText.Kernel.Utils.CompareTool.CompareXmls	(	String	outXmlFile,
		String	cmpXmlFile
	)

inlinevirtual

Utility method that provides simple comparison of the two xml files.

Parameters

outXmlFile	absolute path to the out xml file to compare.
cmpXmlFile	absolute path to the cmp xml file to compare.

Returns: true if xml structures are identical, false otherwise.

◆ CompareXmp() [1/2]

virtual String iText.Kernel.Utils.CompareTool.CompareXmp	(	String	outPdf,
		String	cmpPdf
	)

inlinevirtual

Compares xmp metadata of the two given PDF documents.

Parameters

outPdf	the absolute path to the output file, which xmp is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which xmp is to be compared to output file.

Returns: text report on the xmp differences, or null if there are no differences.

◆ CompareXmp() [2/2]

virtual String iText.Kernel.Utils.CompareTool.CompareXmp	(	String	outPdf,
		String	cmpPdf,
		bool	ignoreDateAndProducerProperties
	)

inlinevirtual

Compares xmp metadata of the two given PDF documents.

Parameters

outPdf	the absolute path to the output file, which xmp is to be compared to cmp-file.
cmpPdf	the absolute path to the cmp-file, which xmp is to be compared to output file.
ignoreDateAndProducerProperties	true, if to ignore differences in date or producer xmp metadata properties.

Returns: text report on the xmp differences, or null if there are no differences.

◆ DisableCachedPagesComparison()

virtual iText.Kernel.Utils.CompareTool iText.Kernel.Utils.CompareTool.DisableCachedPagesComparison ( )

inlinevirtual

Disables the default logic of pages comparison.

Disables the default logic of pages comparison. This option makes sense only for CompareByCatalog(iText.Kernel.Pdf.PdfDocument, iText.Kernel.Pdf.PdfDocument) method.

By default, pages are treated as special objects and if they are met in the process of comparison, then they are not checked as objects, but rather simply checked that they have same page numbers in both documents. This behaviour is intended for the CompareByContent(System.String, System.String, System.String) set of methods, because in them documents are compared in page by page basis. Thus, we don't need to check if pages are of the same content when they are met in comparison process, we are sure that we will compare their content or we have already compared them.

However, if you would use CompareByCatalog(iText.Kernel.Pdf.PdfDocument, iText.Kernel.Pdf.PdfDocument) with default behaviour of pages comparison, pages won't be checked at all, every time when reference to the page dictionary is met, only page numbers will be compared for both documents. You can say that in this case, comparison will be performed for all document's catalog entries except /Pages (However in fact, document's page tree structures will be compared, but pages themselves - won't).

Returns: this CompareTool instance.

◆ EnableEncryptionCompare()

virtual iText.Kernel.Utils.CompareTool iText.Kernel.Utils.CompareTool.EnableEncryptionCompare ( )

inlinevirtual

Enables the comparison of the encryption properties of the documents.

Enables the comparison of the encryption properties of the documents. Encryption properties comparison results are returned along with all other comparison results.

IMPORTANT NOTE: this flag affects only the comparison performed by compareByContent methods! CompareByCatalog(iText.Kernel.Pdf.PdfDocument, iText.Kernel.Pdf.PdfDocument) doesn't compare encryption properties because encryption properties aren't part of the document's Catalog.

Returns: this CompareTool instance.

◆ GetCmpReaderProperties()

virtual ReaderProperties iText.Kernel.Utils.CompareTool.GetCmpReaderProperties ( )

inlinevirtual

Gets iText.Kernel.Pdf.ReaderProperties to be passed later to the iText.Kernel.Pdf.PdfReader of the cmp document.

Documents for comparison are opened in reader mode. This method is intended to alter iText.Kernel.Pdf.ReaderProperties which are used to open the cmp document. This is particularly useful for comparison of encrypted documents.

For more explanations about what outDoc and cmpDoc are see last paragraph of the CompareTool class description.

Returns

iText.Kernel.Pdf.ReaderProperties instance to be passed later to the iText.Kernel.Pdf.PdfReader of the cmp document.

◆ GetOutReaderProperties()

virtual ReaderProperties iText.Kernel.Utils.CompareTool.GetOutReaderProperties ( )

inlinevirtual

Gets iText.Kernel.Pdf.ReaderProperties to be passed later to the iText.Kernel.Pdf.PdfReader of the output document.

Documents for comparison are opened in reader mode. This method is intended to alter iText.Kernel.Pdf.ReaderProperties which are used to open the output document. This is particularly useful for comparison of encrypted documents.

For more explanations about what outDoc and cmpDoc are see last paragraph of the CompareTool class description.

Returns

iText.Kernel.Pdf.ReaderProperties instance to be passed later to the iText.Kernel.Pdf.PdfReader of the output document.

◆ SetCompareByContentErrorsLimit()

virtual iText.Kernel.Utils.CompareTool iText.Kernel.Utils.CompareTool.SetCompareByContentErrorsLimit ( int compareByContentMaxErrorCount )

inlinevirtual

Sets the maximum errors count which will be returned as the result of the comparison.

Parameters

compareByContentMaxErrorCount the errors count.

Returns: this CompareTool instance.

◆ SetEventCountingMetaInfo()

virtual void iText.Kernel.Utils.CompareTool.SetEventCountingMetaInfo ( IMetaInfo metaInfo )

inlinevirtual

Sets iText.Commons.Actions.Contexts.IMetaInfo info that will be used for both read and written documents creation.

Parameters

metaInfo meta info to set

◆ SetGenerateCompareByContentXmlReport()

virtual iText.Kernel.Utils.CompareTool iText.Kernel.Utils.CompareTool.SetGenerateCompareByContentXmlReport ( bool generateCompareByContentXmlReport )

inlinevirtual

Enables or disables the generation of the comparison report in the form of an xml document.

IMPORTANT NOTE: this flag affects only the comparison performed by compareByContent methods!

Parameters

generateCompareByContentXmlReport true to enable xml report generation, false - to disable.

Returns: this CompareTool instance.

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ CompareArrays()

◆ CompareBooleans()

◆ CompareByCatalog()

◆ CompareByContent() [1/5]

◆ CompareByContent() [2/5]

◆ CompareByContent() [3/5]

◆ CompareByContent() [4/5]

◆ CompareByContent() [5/5]

◆ CompareDictionaries()

◆ CompareDictionariesStructure() [1/2]

◆ CompareDictionariesStructure() [2/2]

◆ CompareDocumentInfo() [1/2]

◆ CompareDocumentInfo() [2/2]

◆ CompareLinkAnnotations()

◆ CompareNames()

◆ CompareNumbers()

◆ CompareStreams()

◆ CompareStreamsStructure()

◆ CompareStrings()

◆ CompareTagStructures()

◆ CompareVisually() [1/2]

◆ CompareVisually() [2/2]

◆ CompareXmls() [1/2]

◆ CompareXmls() [2/2]

◆ CompareXmp() [1/2]

◆ CompareXmp() [2/2]

◆ DisableCachedPagesComparison()

◆ EnableEncryptionCompare()

◆ GetCmpReaderProperties()

◆ GetOutReaderProperties()

◆ SetCompareByContentErrorsLimit()

◆ SetEventCountingMetaInfo()

◆ SetGenerateCompareByContentXmlReport()