Purpose

DicomModifyImageTagsPlugin is a plugin class to manipulate the image pixel tags in DICOM trees, for example to replace or crop image data in DICOM series and to create a new series or file from it. It preferably works together with modules such as DirectDicomImport to import DICOM series and with DicomModifyMultiFileVolumeExport to export the modified DICOM tree(s). See the example network for such a case.

Limitations:

-This module does not guarantee the standard compliant modification of all DICOM tags although it tries to do so.

Usage

This module requires a valid image input to be able to replace image pixel data in DICOM trees. Note that the input image is required to be of an appropriate pixel format which is supported in DICOM such as 8 or 16 bit signed or unsigned pixel data. Dependent of the DICOM trees not all combinations of pixel type, color model(photometric interpretation), spatial or temporal extents etc. might be supported; this will typically be reported by the exporting module (for example DicomModifyMultiFileVolumeExport) as error. Note that the second Replacement Mode AdjustSliceWise has additional requirements for proper operation, see the field documentation for details.

Windows

Default Panel

../../../Projects/DICOM/MLDicomModify/Modules/mhelp/Images/Screenshots/DicomModifyImageTagsPlugin._default.png

Input Fields

input0

name: input0, type: Image

The input image whose content shall be written into the pixel data tag of the DICOM tree. See Usage for more information about supported and unsupported types. Note that dependent on the Replacement Mode the entire or only fragments of the input image are written into the DCMTree.

inputModifierList

name: inputModifierList, type: MLBase

This input allows the concatenation of this module with other modules for further manipulations of DICOM tags such as DicomModifyTagsPlugin modules for normal tag manipulations. Appended plugin modules are applied first, which means that the last module in a sequence of modification plugins is applied first. This is important if changes of one plugin shall or shall not overwrite changes of another one. Although it seems strange on the first glance, it can make sense to concatenate multiple DicomModifyImageTagsPlugin modules if Replacement Mode is set to AdjustSliceWise. In this way multiple subvolumes can be composed in the exported series. However, overlaps in spatial dimension of these subvolumes are not handled. It is left to the users’ experience to ensure that this prerequisite is fulfilled. If not then already performed changes might be overwritten by other plugins.

Output Fields

outputModifierList

name: outputModifierList, type: MLBase

This output can be connected to those modules which make use of (image) tag manipulations (such as DicomModifyMultiFileVolumeExport) or to concatenate it with other tag manipulators such as DicomModifyTagsPlugin or DicomModifyImageTagsPlugin.

Parameter Fields

Visible Fields

Skip T-Slices If Outside Input Image Extent

name: skipOutrangedTSlices, type: Bool, default: FALSE

If Replacement Mode is AdjustSliceWise then in the time and u dimension there is a no direct way to find out which time point or position in the u dimension shall be replaced or not. The time and u dimension information in ML images is not reliable enough for such operations or can be ambiguous. Therefore the extent of the input subimage in t and u is taken as range for the possible replacement of frames. A DICOM frame to be manipulated which has a known position in z, t, and u dimension can be overlapped with this range. If it is located in this range its content can be replaced, otherwise it must be determined whether a manipulation shall be refused or whether the original data shall be passed though. If Skip T-Slices If Outside Input Image Extent / Skip T-Slices If Outside Input Image Extent is disabled then frames outside the input range are passed through without manipulating the image pixel data, otherwise the manipulation of the frame is refused. For example: When exporting a frame outside the t / u dimension extent of the input image with DicomModifyMultiFileVolumeExport, it will be exported with unchanged content if Skip T-Slices If Outside Input Image Extent / Skip T-Slices If Outside Input Image Extent is disabled, otherwise the frame will not be exported at all.

Skip U-Slices If Outside Input Image Extent

name: skipOutrangedUSlices, type: Bool, default: FALSE

See Skip T-Slices If Outside Input Image Extent for details.

Replacement Mode

name: replacementMode, type: Enum, default: GlobalReplace

This field controls the input image region which is written into the DCMTree pixel tag.

Values:

Title Name Description
Global Replace GlobalReplace

This mode takes the entire input image, writes it into the pixel data tag of the DICOM tree and adjusts other tags to make it as standard compliant as possible.

Important note: In contrast to the AdjustSliceWise* mode, this mode updates the tags ImageOrientationPatient, PixelSpacing, SpacingBetweenSlices, or SliceThickness.

Adjust Slice Wise AdjustSliceWise

This mode is significant more complex than the GlobalReplace mode, because it tries to determine the region in world space which overlaps with the DICOM tree, requests the region from the input image and adjusts the pixel data tag appropriately. If no overlap exists then the DICOM tree is not manipulated and the manipulation is considered as failed. Often this is even desirable to avoid that DICOM trees are exported which do not overlap with - for example - a cropped region. Requirements for proper operation:

  • The caller of the tag manipulation must pass additional information together with the DICOM tree - the world space coordinate system in which the DICOM tree is located must be available as Matrix4 field named “worldToVoxelMatrix”. Currently only DicomModifyMultiFileVolumeExport does this when it exports MultiFileVolumes. Together with the information of the Image Position Patient and Image Orientation Patient tags of the DICOM frame itself the DicomModifyImageTagsPlugin can properly determine and write the overlapping region of the image and export it to the output.
  • In a few cases the DICOM frame might not provide Image Position Patient and Image Orientation Patient tags. This for example happens with secondary captures, where the DICOM standard does not describe these tags as mandatory. In such cases the image orientation and position is derived from a unit matrix which means that scale factors are considered as (1,1,1), while rotation and shearing are unchanged. If any information about the position of the frame inside of MultiFileVolume is given as Vector6 field named “framePosition” then the translational part is assumed to be located at that position. This usually leads to a spatial position (0,0,z) with z determined from the frame position in the MultiFileVolume. The module making use of the DicomModifyImageTagsPlugin must provide this to make that work, which, as mentioned above for the “worldToVoxelMatrix” field, is currently only done by DicomModifyMultiFileVolumeExport. If such a “framePosition” field is not provided then all locations of frames without position or orientation information fall back to position (0,0,0).
  • Additional limitations exist for extents > 1 in time or u dimension. See Skip T-Slices If Outside Input Image Extent and Skip U-Slices If Outside Input Image Extent for details.
  • The world to voxel matrix passed together with the DICOM tree and the world to voxel matrix of the connected input image should differ only in the translational part; otherwise a correct overlap detection for frames is not possible. This implies that the connected input image may be a subimage or a translated volume, but it should not be rescaled, resampled, rotated, nor sheared or perspectively transformed.
  • Important note: In contrast to the GlobalReplace mode, this mode does not update the tags ImageOrientationPatient, PixelSpacing, SpacingBetweenSlices, or SliceThickness.**

ImageType Value 3

name: imageTypeValue3, type: Enum, default: DoNotModifyImageType

Determines how the third value of Image Type (0008,0008) tag for NM modality images shall be set. Note that according to this setting the configuration of the index vectors in the DICOM data set must be set correctly, see the documentation of the specific modes for details.

Values:

Title Name Description
DoNotModifyImageType DoNotModifyImageType The third value of the Image Type (0008,0008) tag shall not be modified.
STATIC STATIC The third value of the Image Type (0008,0008) tag is set to STATIC . This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the Energy Window Vector (0054,0010), and the Detector Vector (0054,0020).
WHOLE BODY WHOLE BODY The third value of the Image Type (0008,0008) tag is set to WHOLE BODY . This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the Energy Window Vector (0054,0010), and the Detector Vector (0054,0020).
DYNAMIC DYNAMIC The third value of the Image Type (0008,0008) tag is set to DYNAMIC . This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the Energy Window Vector (0054,0010), the Detector Vector (0054,0020), the Phase Vector (0054,0030), and the Time Slice Vector (0054,0100).
GATED GATED The third value of the Image Type (0008,0008) tag is set to GATED. This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the Energy Window Vector (0054,0010), the Detector Vector (0054,0020), the R-R Interval Vector (0054,0060), and the Time Slot Vector (0054,0070).
TOMO TOMO The third value of the Image Type (0008,0008) tag is set to TOMO . This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the Energy Window Vector (0054,0010), the Detector Vector (0054,0020), the Rotation Vector (0054,0050), and the Angular View (0054,0090).
GATED TOMO GATED TOMO The third value of the Image Type (0008,0008) tag is set to GATED TOMO . This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the Energy Window Vector (0054,0010), the Detector Vector (0054,0020), the Rotation Vector (0054,0050), the R-R Interval Vector (0054,0060), the Time Slot Vector (0054,0070), and the Angular View Vector (0054,0090).
RECON TOMO RECON TOMO The third value of the Image Type (0008,0008) tag is set to RECON TOMO . This also implies that the index vector in the NM image, which is required by the DICOM standard, is the Slice Vector (0054,0080).
RECON GATED TOMO RECON GATED TOMO The third value of the Image Type (0008,0008) tag is set to RECON GATED TOMO . This also implies that the index vectors in the NM image, which are required by the DICOM standard, are the R-R Interval Vector (0054,0060), the Time Slot Vector (0054,0070), and the Slice Vector (0054,0080).

Z

name: zDimIndexVector, type: Enum, default: DoNotModifyIndexVectors

Mode describing to which NM index vector the z-dimension extent of the image shall be mapped.

Values:

Title Name Description
Do Not Modify Index Vectors DoNotModifyIndexVectors No index vector shall be modified according to the spatial extent of the image.
Energy Window Vector EnergyWindowVector The spatial extent of the image shall be associated with Energy Index Vector (0054,0010).
Detector Vector DetectorVector The spatial extent of the image shall be associated with Detector Vector (0054,0020).
Phase Vector PhaseVector The spatial extent of the image shall be associated with Phase Vector (0054,0030).
Rotation Vector RotationVector The spatial extent of the image shall be associated with Rotation Vector (0054,0050).
RRInterval Vector RRIntervalVector The spatial extent of the image shall be associated with R-R Interval Vector (0054,0060).
Time Slot Vector TimeSlotVector The spatial extent of the image shall be associated with Time Slot Vector (0054,0070).
Slice Vector SliceVector The spatial extent of the image shall be associated with Slice Vector (0054,0080).
Angular View Vector AngularViewVector The spatial extent of the image shall be associated with Angular View Vector (0054,0090).
Time Slice Vector TimeSliceVector The spatial extent of the image shall be associated with Time Slice Vector (0054,0100).

T

name: tDimIndexVector, type: Enum, default: DoNotModifyIndexVectors

Mode describing to which NM index vector the t-dimension extent of the image shall be mapped. See Z for details.

U

name: uDimIndexVector, type: Enum, default: DoNotModifyIndexVectors

Mode describing to which NM index vector the u-dimension extent of the image shall be mapped. See Z for details.