Purpose

DicomTreeCompare compares two DICOM trees which can be provided via different inputs. It displays the differences between them and can optionally post ML errors if the difference is not as expected. It is especially useful for testing purposes.

Different comparisons are available:

  • An explicit difference displayed as report in Summary of changes. It is a condensed report regarding the settings, and which is compared with Expected summary of changes to see whether result is as expected. This is the typical comparison used in tests.
  • A more human readable comparison is presented in tab Difference. It is a color-coded line-wise difference of Input1Dump and Input2Dump, independent of any expectations or exclusion or so (e.g. Expected summary of changes or Exclude From Changes). This is only for a visual comparison and for debugging purposes, not for testing.

Details

Explanation of a known issue of DicomTreeCompare:

  • The comparison of DCMTree structures creates sub-DCMTrees which describe the difference between DCMTrees. These differences usually do not contain the private creator tags of sequence items since these are not changed. Displaying these sub-DCMTrees therefore does not have the private creator information any more and therefore shows private tags with “invalid private create” or “unknown private tag”. This issue only affects the readability of the comparison results, however, not the correctness of the result comparison. Thus the results can safely be used for testing.

Windows

Default Panel

../../../Projects/DICOM/MLDicomAnalysis/Modules/mhelp/Images/Screenshots/DicomTreeCompare._default.png

Input Fields

input0

name: input0, type: Image

This is the first image connector which can be used to provide the first of the two DICOM trees to be compared; it is is only used if Input Selector0 is set accordingly.

input1

name: input1, type: Image

This is the second image connector which can be used to provide the second of the two DICOM trees to be compared; it is only used if Input Selector1 is set accordingly.

inputBase0

name: inputBase0, type: DicomTree/MultiFileVolumeListRefCounted(MLBase)

This is the first Base connector which can be used to provide the first of the two DICOM trees to be compared; it is only used if Input Selector0 is set accordingly. It supports DICOM tree and MultiFileVolumeList Base objects as inputs.

For accessing this object via scripting see the Scripting Reference: MLABDicomTree.

inputBase1

name: inputBase1, type: DicomTree/MultiFileVolumeListRefCounted(MLBase)

This is the second Base connector which can be used to provide the second of the two DICOM trees to be compared; it is only used if Input Selector1 is set accordingly. It supports DICOM tree and MultiFileVolumeList Base objects as inputs.

For accessing this object via scripting see the Scripting Reference: MLABDicomTree.

Parameter Fields

Visible Fields

Input Selector0

name: inputSelector0, type: Enum, default: ImageConnector #0

This field determines from which input the first of the two DICOM trees to compare shall be retrieved.

Values:

Title Name Description
Image Connector #0 ImageConnector #0 If Input Selector0 is set to this mode, then the first DICOM tree used for comparison is retrieved from the first image connector.
Base Connector #0 BaseConnector #0 If Input Selector0 is set to this mode, then the first DICOM tree used for comparison is retrieved from the first Base connector where DICOM tree or MultiFileVolumeList base objects are allowed.
File File If Input Selector0 is set to this mode, then the first DICOM tree used for comparison is loaded from the file path given in Input File Path0; an empty file path is allowed and results to an empty tree for comparison.

InIdx (inputVolumeIndex0)

name: inputVolumeIndex0, type: Integer, default: 0

If Input Selector0 determines the first Base connector as DICOM tree source and a MultiFileVolumeList with multiple volumes is connected, then InIdx determines the list entry the tree is taken from.

#Volumes (numVolumes0)

name: numVolumes0, type: Integer, default: 0

Shows the number of available volumes at the DICOM tree source determined by Input Selector0; for image connectors and connected DICOM tree objects this is typically zero or one; for a MultiFileVolumeList it can be an arbitrary number.

Input File Path0

name: inputFilePath0, type: String

If Input Selector0 is set to File, then the first DICOM tree used for comparison is loaded from the file path given in Input File Path0; an empty file path is allowed and results to an empty tree for comparison.

Input Selector1

name: inputSelector1, type: Enum, default: ImageConnector #1

This field determines from which the input the second of the two DICOM trees to compare shall be retrieved.

Values:

Title Name Description
Image Connector #1 ImageConnector #1 If Input Selector1 is set to this mode, then the second DICOM tree used for comparison is retrieved from the second image connector.
Base Connector #1 BaseConnector #1 If Input Selector1 is set to this mode, then the second DICOM tree used for comparison is retrieved from the second Base connector where DICOM tree or MultiFileVolumeList base objects are allowed.
File File If Input Selector1 is set to this mode, then the first DICOM tree used for comparison is loaded from the file path given in Input File Path1; an empty file path is allowed and results to an empty tree for comparison.

InIdx (inputVolumeIndex1)

name: inputVolumeIndex1, type: Integer, default: 0

If Input Selector1 determines the second Base connector as DICOM tree source and a MultiFileVolumeList with multiple volumes is connected, then InIdx determines the list entry the tree is taken from.

#Volumes (numVolumes1)

name: numVolumes1, type: Integer, default: 0

Shows the number of available volumes at the DICOM tree source determined by Input Selector1; for image connectors and connected DICOM tree objects this is typically zero or one; for MultiFileVolumeList then can be an arbitrary number.

Input File Path1

name: inputFilePath1, type: String

If Input Selector1 is set to File, then the first DICOM tree used for comparison is loaded from the file path given in Input File Path1; an empty file path is allowed and results to an empty tree for comparison.

Expected summary of changes

name: expectedChanges, type: String, default: No differences found

If two DICOM trees are compared then a summary of all changes is shown in Summary of changes; if Expected summary of changes and Summary of changes differ then the comparison is considered as failed, otherwise as successful.

Exclude From Changes

name: excludeFromChanges, type: String

In this field a line separated list of DICOM tag ids can be added which will be removed from the result tag dumps. Note that removed or added tags are only influenced by this if they have the flags Hide reports from excluded tags from 'Added' result or Hide reports from excluded tags from 'Removed' result, respectively. The tag must either have the format (ABCD,EFGH) with 32 bit hexadecimal numbers ABCD and EFGH or the space-less tag name such as Modality of PatientsName.

Post Error If Difference Is Found

name: postErrorIfDifferenceIsFound, type: Bool, default: TRUE

If this flag enabled then a failing comparison leads to the post of an ML error to the MeVisLab error handler which, for example, can be very useful for tests. If disabled then no ML error is posted.

Error Post Prefix

name: errorPostPrefix, type: String, default: Failure in DICOM tree comparison:

If the flag Post Error If Difference Is Found is enabled then a failing comparison leads to the post of an ML error to the MeVisLab error handler which will have this string as introduction. This can be useful to differentiate error messages from different tests.

Also Compare Num Tag Values

name: alsoCompareNumTagValues, type: Bool, default: FALSE

If this flag is enabled then in the compared tag dumps also the number of values in each tag is listed and will also be compared; otherwise the number of values will not be compared. Since that this flag changes the comparison results it should be set before setting up comparison results with Set summary as 'Expected Changes'. It is recommended to enable this flag because it compares more information.

Compare Recursively

name: compareRecursively, type: Bool, default: FALSE

If enabled then the DICOM trees are compared recursively which is more precise but also more time and memory consuming. Note that flat comparison (if this flag is off) also detects changes in deeper levels of the tree but then only displays a change of the top level sequence tag which contains this tag.

Compare Multiplicity

name: compareMultiplicity, type: Bool, default: FALSE

If enabled then also the value multiplicities of tags are compared, if disabled then not. Usually the multiplicity is not compared since it often has not influence to the tag behavior; therefore it is disabled by default.

Compare Multi Frame Data

name: compareMultiFrameData, type: Bool, default: TRUE

If enabled then data of multi-frame tags is compared, otherwise not. Note comparing the data of multi-frame tags with can slow down tree comparison significantly on large ones and may not be desired especially in tests where image (or pixel) data is compared anyway.

Decode Private Tags

name: decodePrivateTags, type: Bool, default: TRUE

If enabled then private tags are decoded as far as decoders are available, otherwise not.

Set summary as ‘Expected Changes’

name: setAsExpectedResult, type: Trigger

This is a convenience button to copy the content of Summary of changes to Expected summary of changes to determine the expected result for future comparisons.

Update Mode

name: updateMode, type: Enum, default: Auto Update On Two Valid Inputs

Controls when a comparison is started.

Values:

Title Name Description
Update On Two Valid Inputs Auto Update On Two Valid Inputs If Update Mode is set to this mode then a comparison is automatically started on parameter or input changes and if two valid trees are available at the inputs.
Clear Auto Clear If Update Mode is set to this mode then a comparison takes place only if Compare is pressed.

Compare

name: compare, type: Trigger

Starts the comparison; it is only active if Update Mode is set to automatic clear.

Tag Dump Size

name: tagDumpSize, type: Integer, default: 10000

Determines the rough maximum number of characters in the output fields which show tag dumps; this is used to avoid that user interfaces become slow or even become overloaded with too large tag dumps.

Hide reports from excluded tags from ‘Added’ result

name: removeIgnoreIdsInAddedTags, type: Bool, default: FALSE

If enabled then tags with ids ignored in Exclude From Changes are also removed from Added reports. Note that empty subtrees may remain after hiding tags in reports; see Clean up empty trees in 'Added' result to hide these subtrees, too.

Clean up empty trees in ‘Added’ result

name: cleanupEmptyTreesInAddedTags, type: Bool, default: FALSE

If enabled then empty trees in trees of added tags will be removed from the comparison repport; this is often wanted if result trees are empty after ignoring added tags with Hide reports from excluded tags from 'Added' result in Exclude From Changes.

Hide reports from excluded tags from ‘Removed’ result

name: removeIgnoreIdsInRemovedTags, type: Bool, default: FALSE

If enabled then tags with ids ignored in Exclude From Changes are also removed from Removed reports. Note that empty subtrees may remain after hiding tags in reports; see Clean up empty trees in 'Removed' result to hide these subtrees, too.

Clean up empty trees in ‘Removed’ result

name: cleanupEmptyTreesInRemovedTags, type: Bool, default: FALSE

If enabled then empty trees in trees of removed tags will be removed from the comparison reports; this is often wanted if result trees are empty after ignoring removed tags with Hide reports from excluded tags from 'Removed' result in Exclude From Changes.

Input1Dump

name: input1Dump, type: String, persistent: no

Shows the original DICOM tags of the first of the two compared DICOM trees. It is also the source for the left side of the line-wise comparison provided in tab Difference.

Input2Dump

name: input2Dump, type: String, persistent: no

Shows the original DICOM tags of the second of the two compared DICOM trees. It is also the source for the left side of the line-wise comparison provided in tab Difference.

Unchanged

name: unchanged, type: String, persistent: no

Shows the dump of all DICOM tags which do not differ between both DICOM tree inputs.

Added

name: added, type: String, persistent: no

Shows the dump of all DICOM tags which are not part of the first of the two compared DICOM trees but in the second one.

Removed

name: removed, type: String, persistent: no

Shows the dump of all DICOM tags which are part of the first of the two compared DICOM trees but not in the second one.

Changed

name: changed, type: String, persistent: no

Shows the dump of all DICOM tags which are part of the first and the second of the two compared DICOM trees but which differ in any way.

Summary of changes

name: allChanges, type: String, persistent: no

Shows the summary of the contents of Added, Removed, and Changed. See Expected summary of changes which is used to describe what is considered as successful comparison result.

Test Passed

name: testPassed, type: Bool, default: FALSE

This flag is enabled after a comparison where Summary of changes and Expected summary of changes are identical; it will be disabled after all tests where they differ.

Clear DICOM caches before compare

name: clearDICOMCachesBeforeCompare, type: Bool, default: FALSE

If checked then cached DICOM data is cleared before comparisons. If DICOM data in, for example, a file is updated/overwritten after caching it, an enabled Clear DICOM caches before compare may prevent comparing against outdated information. It, however, can slow down DICOM imports, because file contents have to be reloaded then.

Clear DICOMCaches

name: clearDICOMCaches, type: Trigger

Clear cached DICOM data. See Clear DICOM caches before compare for details.

Font Size

name: fontSize, type: Integer, default: 9, minimum: 4

Controls the font size of the Web View control shown in tab Difference.

Wrap Column

name: wrapColumn, type: Integer, default: 100

The column in the Difference tab at which columns are wrapped to prevent too wide difference views.

Hidden Fields

htmlDiff

name: htmlDiff, type: String, persistent: no

This is a hidden field containing the content of the web view display in tab Difference as pure HTML. Note that the HTML difference shows all differences independent of any expectations or exclusion or so (e.g. Expected summary of changes or Exclude From Changes).