Tool function namespace with many tool functions for the conversion of DICOM information and tag values to comparable ML information objects. More...

Classes
class	AdvancedTagSetUpArgs
	Some dedicated parameters for advanced tag setups when setting pixel data and related tags in DICOM files. More...

Functions
ML_MLToDicomTools_EXPORT void	getSpacingImagePositionAndOrientationPatientFromMLWorldMatrix (MedicalImageProperties imgProps, Vector3 &pixelSpacing, Vector3 &imagePositionPatient, Vector6 &imageOrientationPatient, std::string *issueMessages=nullptr)
	Gets DICOM compliant values for tags Pixel Spacing, Image Position Patient, and Image Orientation Patient from the ML world matrix in imgProps. More...

ML_MLToDicomTools_EXPORT void	setPixelData (DCMTree::TagPtr pixelDataTag, PagedImage &inImg, MLDataType overrideDataType=ML_INVALID_DATA_TYPE, double minVal=nullptr, double maxVal=nullptr, const SubImageBox *overrideBox=nullptr)
	Gets an input image as pixel data with getTile from inImg and sets it as value of pixelDataTag. More...

ML_MLToDicomTools_EXPORT void	setVectorGridData (DCMTree::TagPtr vecGridDataTag, PagedImage &inImg)
	Gets a floating point vector field with getTile from inImg and sets it as OF value of the vecGridDataTag. More...

ML_MLToDicomTools_EXPORT std::string	addAndSetSEGPixelDataTag (DCMTree::TreePtr dcmTree, const BitImage &bitImage, bool writePadded)
	Stores the bit mask given by BitImage in newly created PixelData tag in dcmTree; it does not set any related tags such as Rows, Columns etc. More...

ML_MLToDicomTools_EXPORT std::string	appendImagePixelModuleTags (DCMTree::TreePtr resultTree, unsigned int samplesPerPixel, const std::string &photometricInterpretation, unsigned int rows, unsigned int columns, unsigned int bitsAllocated, unsigned int bitsStored, unsigned int highBit, unsigned int pixelRepresentation, bool writePlanarConfiguration=false, unsigned int planarConfiguration=0, bool writeMinMaxPixelValue=false, double smallestPixelValue=0, double largestPixelValue=0, MLint numberOfColorChannels=0, const std::vector< std::string > &cDimInfos=std::vector< std::string >())
	Appends required DICOM tags to resultTree according to DICOM standard, C.7.6.3 Image Pixel Module Attributes. More...

ML_MLToDicomTools_EXPORT std::string	setSegmentationBinaryImagePixelTags (DCMTree::TreePtr &dcmTree, const BitImage &inputBitImage)
	Set Image Pixel / Segmentation Image Module Attribute tags for a binary segmentation image using setImagePixelTags() and appendImagePixelModuleTags(), specific tags for the SEG IOD and smallest/largest pixel values are not added/written. More...

ML_MLToDicomTools_EXPORT std::string	setSegmentationFractionalImagePixelTags (DCMTree::TreePtr &dcmTree, const PagedImage &inputBitImage)
	Set Image Pixel / Segmentation Image Module Attribute tags for a fractional segmentation image using setImagePixelTags() and appendImagePixelModuleTags(), specific tags for the SEG IOD and smallest/largest pixel values are not added/written. More...

ML_MLToDicomTools_EXPORT SubImageBox	determineFrameRegion (DCMTree::TreePtr dcmTree, const FieldContainer treeInfos, PagedImage &inImg, Vector3 srcImgPosPatient=nullptr, Vector3 dstImgPosPatient=nullptr, std::string errorMessage=nullptr, bool useFullTUDimExtentFromInImgInSliceWiseUpdate=false, AdvancedTagSetUpArgs *configParams=nullptr)
	If possible then determine and return the region in inImg which corresponds to the region the dcmTree belongs to. More...

ML_MLToDicomTools_EXPORT bool	setUpPhotometricInterpretation (DCMTree::TreePtr dcmTree, MLint numColorChannels, const std::vector< std::string > &cDimInfos)
	Evaluates the number of color channels and the cDimInfos of the input image, checks for valid settings and sets the Photometric Interpretation tags in dcmTree such that it fits best the ML image. More...

ML_MLToDicomTools_EXPORT std::string	setImagePixelTags (DCMTree::TreePtr dcmTree, const FieldContainer treeInfos, PagedImage &inImg, bool adjustSliceWise, bool reportNonOrthoWorldMatrix, AdvancedTagSetUpArgs configParams=nullptr)
	Gets the input image and its properties, checks whether it is DICOM-like and if yes it sets image pixel related tags such that dcmTree contains the input image afterwards. More...

Detailed Description

Tool function namespace with many tool functions for the conversion of DICOM information and tag values to comparable ML information objects.

Namespace with tool functions converting DICOM information and tag values to comparable ML information objects.

Function Documentation

◆ addAndSetSEGPixelDataTag()

ML_MLToDicomTools_EXPORT std::string ml::MLToDicomTools::addAndSetSEGPixelDataTag	(	DCMTree::TreePtr	dcmTree,
		const BitImage &	bitImage,
		bool	writePadded
	)

Stores the bit mask given by BitImage in newly created PixelData tag in dcmTree; it does not set any related tags such as Rows, Columns etc.

Parameters

dcmTree	The tree into which the new PixelData tags shall be inserted.
bitImage	The BitImage which provides the bit mask to be stored in dcmTree.
writePadded	If enabled then frames of written binary images are padded between frames, which is NOT DICOM compliant and only for backward compatibility, however, it is strongly recommended to use false as default.

Returns: An empty string on success, otherwise a textual description of the problem.

◆ appendImagePixelModuleTags()

ML_MLToDicomTools_EXPORT std::string ml::MLToDicomTools::appendImagePixelModuleTags	(	DCMTree::TreePtr	resultTree,
		unsigned int	samplesPerPixel,
		const std::string &	photometricInterpretation,
		unsigned int	rows,
		unsigned int	columns,
		unsigned int	bitsAllocated,
		unsigned int	bitsStored,
		unsigned int	highBit,
		unsigned int	pixelRepresentation,
		bool	writePlanarConfiguration = `false`,
		unsigned int	planarConfiguration = `0`,
		bool	writeMinMaxPixelValue = `false`,
		double	smallestPixelValue = `0`,
		double	largestPixelValue = `0`,
		MLint	numberOfColorChannels = `0`,
		const std::vector< std::string > &	cDimInfos = `std::vector< std::string >()`
	)

Appends required DICOM tags to resultTree according to DICOM standard, C.7.6.3 Image Pixel Module Attributes.

Pixel data is not written, this must be done explicitly.

samplesPerPixel can be passed 0 if alternatively a valid numberOfColorChannels>0 and cDimInfos-vector is passed.
photometricInterpretation can be passed empty if alternatively a valid numberOfColorChannels>0 and cDimInfos-vector is passed.

◆ determineFrameRegion()

ML_MLToDicomTools_EXPORT SubImageBox ml::MLToDicomTools::determineFrameRegion	(	DCMTree::TreePtr	dcmTree,
		const FieldContainer *	treeInfos,
		PagedImage &	inImg,
		Vector3 *	srcImgPosPatient = `nullptr`,
		Vector3 *	dstImgPosPatient = `nullptr`,
		std::string *	errorMessage = `nullptr`,
		bool	useFullTUDimExtentFromInImgInSliceWiseUpdate = `false`,
		AdvancedTagSetUpArgs *	configParams = `nullptr`
	)

If possible then determine and return the region in inImg which corresponds to the region the dcmTree belongs to.

If not possible an empty box is returned.

Parameters

dcmTree	The DCMTree which shall be modified with the new region.
treeInfos	The FieldContainer possibly passed with dcmTree for modification. Must contain a Matrix4 field (or a StringField with same- formatted value) named "worldToVoxelMatrix" with the worldToVoxelMatrix of the volume the dcmTree belongs to. If a world position cannot be determined from the DICOM tags in dcmTree then the value of a Vector6Field named "framePosition" is taken if it exists; if not then (0,0,0,0,0,0) is used instead. This possibly happens in the case of secondary captures which do not need to set ImagePositionPatient or Image Orientation Patient tags.
inImg	The valid ML Paged image for which the overlapping region with the dcmTree shall be determined.
srcImgPosPatient	Ignored if nullptr otherwise the content of the ImagePositionPatient tag of dcmTree is returned for convenience.
dstImgPosPatient	Ignored if nullptr otherwise the ImagePositionPatient corresponding to v1 of the the returned SubImageBox is returned.
errorMessage	If non nullptr then possible error messages are appended to this string; if nullptr such messages are posted as ML_PRINT_ERROR.
useFullTUDimExtentFromInImgInSliceWiseUpdate	If true then returned frame regions with valid xyz-extents make use of inImg.getExtent().v2.t and .u determined from the inImg.getExtent().t and .u; if false then these extents are set to 1 or - for t if available - to NumberOfTemporalPositions as long as it is inside the t-range extent of inImg.
configParams	This pointer can be passed nullptr; if non nullptr then its content is taken for more specific setups of, for example, NM modality tag setups or the way how or if frames are skipped in t and u dimension.

Returns

- An empty SubImageBox and empty/no error message if the region corresponding to dcmTree is out of the input image range,

an empty SubImageBox and a non-empty error message on any parameter error, and
a non-empty SubImageBox and empty/no error message for a successfully determined overlapping region with the input image.

◆ getSpacingImagePositionAndOrientationPatientFromMLWorldMatrix()

ML_MLToDicomTools_EXPORT void ml::MLToDicomTools::getSpacingImagePositionAndOrientationPatientFromMLWorldMatrix	(	MedicalImageProperties	imgProps,
		Vector3 &	pixelSpacing,
		Vector3 &	imagePositionPatient,
		Vector6 &	imageOrientationPatient,
		std::string *	issueMessages = `nullptr`
	)

Gets DICOM compliant values for tags Pixel Spacing, Image Position Patient, and Image Orientation Patient from the ML world matrix in imgProps.

Parameters

imgProps	The MedicalImageProperties instance from which the settings are to be extracted.
pixelSpacing	Returns the value for pixel spacing; the 3rd is also set and could be used for Spacing Between Slices.
imagePositionPatient	Returns the value for Image Position Patient Tag adapted from ML world matrix to DICOM coordinate system.
imageOrientationPatient	Returns the value for Image Orientation Patient Tag in the same order as needed in the corresponding DICOM tag, which means that entries 0-2 contain the direction cosine values for the x direction, and 3-5 the ones for the y direction.
issueMessages	If passed as nullptr then non orthogonal world matrices are reported with ML_PRINT_ERROR, otherwise it is appended to *issueMessages. In all cases normalized x- and y-orientation vectors are returned in imageOrientationPatient.

◆ setImagePixelTags()

ML_MLToDicomTools_EXPORT std::string ml::MLToDicomTools::setImagePixelTags	(	DCMTree::TreePtr	dcmTree,
		const FieldContainer *	treeInfos,
		PagedImage &	inImg,
		bool	adjustSliceWise,
		bool	reportNonOrthoWorldMatrix,
		AdvancedTagSetUpArgs *	configParams = `nullptr`
	)

Gets the input image and its properties, checks whether it is DICOM-like and if yes it sets image pixel related tags such that dcmTree contains the input image afterwards.

Parameters

dcmTree	The DICOM tree to be modified.
treeInfos	A FieldContainer which - if not nullptr - can contain additional user defined information fields about dcmTree. Some classes such as DicomModifyMultiFileVolumeExport append it to DicomModifyTagsPluginBase derived instances.
inImg	The PagedImage used as source for the image and image properties to be stored in dcmTree.
adjustSliceWise	If false then the entire input image is set as it is without further considerations of its location; if true then treeInfos must contain the Matrix4 field "worldToVoxelMatrix" (or a StringField with same formatted value) the worldToVoxelMatrix of the volume the dcmTree belongs to. Then the location of dcmTree relative to the input image can be determined and overlapping image regions are copied to dcmTree. If no overlaps are detected the dcmTree is not modified and the return will contain a message that the frame is skipped. Note that for overlap detection the world matrices of inImg and "worldToVoxelMatrix" may differ only in translations. For other modifications the overlap detection is not properly defined. The ImageOrientationPatient tag will only be set if adjustSliceWise is true; otherwise it is left unchanged.
reportNonOrthoWorldMatrix	If true and if adjustSliceWise is false then a non-orthogonal world matrix will be added silently while otherwise it will be commented with a non empty warn return string.
configParams	This pointer can be passed nullptr; if non nullptr then its content is taken for more specific setups of, for example, NM modality tag setups.

Returns: An empty string on success, otherwise a cumulative descriptive string of all problems.

Notes:

The following tags will be set/replaced/updated when pixel data is modified: DCMTree_PixelSpacing , DCMTree_ImageOrientationPatient , DCMTree_ImagePositionPatient , DCMTree_SliceThickness , DCMTree_SamplesPerPixel , DCMTree_PhotometricInterpretation, DCMTree_Columns , DCMTree_Rows , DCMTree_PixelRepresentation , DCMTree_BitsAllocated , DCMTree_BitsStored , DCMTree_HighBit , DCMTree_PlanarConfiguration , DCMTree_PixelData ,
DCMTree_SmallestImagePixelValue , DCMTree_LargestImagePixelValue ,

Note that in secondary captures the additional limitation exists that DCMTree_ImagePositionPatient and DCMTree_ImageOrientationPatient tags will only be updated if position or orientation information exist in the incoming dcmTree; they will not be added if none of both exists.

Set when spatial or temporal extent is > 1: DCMTree_NumberOfFrames , DCMTree_NumberOfTemporalPositions,

The following tags are removed (perhaps after reading their values): DCMTree_ACR_NEMA_ImageLocation , DCMTree_ACR_NEMA_ImagePosition , DCMTree_ACR_NEMA_Location , DCMTree_NumberOfFrames , DCMTree_NumberOfTemporalPositions, DCMTree_SliceLocation ,

In cases of Nuclear medicine modality trees also the index vectors DCMTree_EnergyWindowVector, DCMTree_DetectorVector, DCMTree_PhaseVector, DCMTree_RotationVector, DCMTree_RRIntervalVector, DCMTree_TimeSlotVector, DCMTree_SliceVector, DCMTree_AngularViewVector, DCMTree_TimeSliceVector, their corresponding number of item tags DCMTree_NumberOfEnergyWindows, DCMTree_NumberOfDetectors, DCMTree_NumberOfPhases, DCMTree_NumberOfRotations, DCMTree_NumberOfRRIntervals, DCMTree_NumberOfTimeSlots, DCMTree_NumberOfSlices, DCMTree_NumberOfFramesInRotation, DCMTree_NumberOfFramesInPhase, the DCMTree_FrameIncrementPointer and DCMTree_ImageType might be adjusted, replaced or modified dependent on the passed configParams.

If image tags are modified with this function the following potential problems should always be considered: LUT, window/center, Rescale Intercept, Rescale Slope, Dose Grid Scaling and similar tags are completely ignored. If image contents are replaced by modified pixel intensities or color formats these tags require considerations, because they could influence the result when using or importing the modified tree somewhere else.

◆ setPixelData()

ML_MLToDicomTools_EXPORT void ml::MLToDicomTools::setPixelData	(	DCMTree::TagPtr	pixelDataTag,
		PagedImage &	inImg,
		MLDataType	overrideDataType = `ML_INVALID_DATA_TYPE`,
		double *	minVal = `nullptr`,
		double *	maxVal = `nullptr`,
		const SubImageBox *	overrideBox = `nullptr`
	)

Gets an input image as pixel data with getTile from inImg and sets it as value of pixelDataTag.

Note that it is the responsibility of the caller to guarantee that the pixel data tag has a value representation matching the with its data and other tags such as PixelRepresentation and PlanarRepresentation.

Parameters

pixelDataTag	the tag whose value shall be filled with the pixel data
inImg	the PagedImage the data shall be requested from.
overrideDataType	if not ML_INVALID_DATA_TYPE then the data is requested as overrideDataType, otherwise the voxel type of inImg is used.
minVal	if non nullptr then *minVal is set to the minimum voxel value found in requested data.
maxVal	if non nullptr then *maxVal is set to the maximum voxel value found in requested data.
overrideBox	if non nullptr then this box will be used as region requested from inImg; otherwise the entire inImgExtent will be used. Requires a non null tagPtr (first value will be added if necessary), a valid scalar ML voxel type, a valid inImg, a total size of all voxels of the input image * MLSizeof(inDataType) smaller than ML_UINT32_MAX, and enough memory to allocate the voxel field twice temporarily, and color images must be requested in MLuint8Type, single channel images must be one of MLuint8Type, MLuint16Type, MLint8Type, or MLint16Type. If any of the upper facts are not fulfilled a DCMTree::Exception with appropriate text description is thrown.

◆ setSegmentationBinaryImagePixelTags()

ML_MLToDicomTools_EXPORT std::string ml::MLToDicomTools::setSegmentationBinaryImagePixelTags	(	DCMTree::TreePtr &	dcmTree,
		const BitImage &	inputBitImage
	)

Set Image Pixel / Segmentation Image Module Attribute tags for a binary segmentation image using setImagePixelTags() and appendImagePixelModuleTags(), specific tags for the SEG IOD and smallest/largest pixel values are not added/written.

Parameters

dcmTree	is the DICOM tree into which the tags shall be inserted.
inputBitImage	The properties of this BitImage are to be set as tags.

Returns: An empty string on success, otherwise a textual description of the problem.

◆ setSegmentationFractionalImagePixelTags()

ML_MLToDicomTools_EXPORT std::string ml::MLToDicomTools::setSegmentationFractionalImagePixelTags	(	DCMTree::TreePtr &	dcmTree,
		const PagedImage &	inputBitImage
	)

Set Image Pixel / Segmentation Image Module Attribute tags for a fractional segmentation image using setImagePixelTags() and appendImagePixelModuleTags(), specific tags for the SEG IOD and smallest/largest pixel values are not added/written.

Parameters

dcmTree	is the DICOM tree into which the tags shall be inserted.
inputBitImage	The properties of this PagedIMage are to be set as tags.

Returns: An empty string on success, otherwise a textual description of the problem.

◆ setUpPhotometricInterpretation()

ML_MLToDicomTools_EXPORT bool ml::MLToDicomTools::setUpPhotometricInterpretation	(	DCMTree::TreePtr	dcmTree,
		MLint	numColorChannels,
		const std::vector< std::string > &	cDimInfos
	)

Evaluates the number of color channels and the cDimInfos of the input image, checks for valid settings and sets the Photometric Interpretation tags in dcmTree such that it fits best the ML image.

If no matching configuration can be found then the default setting "MONOCHROME2" for single channel and "RGB" other are used. Empty color channel settings with numColorChannels==1 or 3 are assumed as valid and map to MONOCHROME2 and RGB, respectively.

Parameters

dcmTree	The DICOM tree to be modified.
numColorChannels	The extent in the c dimension of the input image.
cDimInfos	The cDimInfos of the input image.

Returns: true if a PhotometricInterpretation could be set up which exactly matches the MLPagedImage configuration, otherwise.

◆ setVectorGridData()

ML_MLToDicomTools_EXPORT void ml::MLToDicomTools::setVectorGridData	(	DCMTree::TagPtr	vecGridDataTag,
		PagedImage &	inImg
	)

Gets a floating point vector field with getTile from inImg and sets it as OF value of the vecGridDataTag.

If necessary the incoming voxel data from inImg will be cast to voxels of Vector3 implicitly on success.

Requires

a non null tagPtr (first value will be added if necessary),
a registered vecf3 voxel type,
a valid inImg,
a total size of all voxels of the input image * 12 (3 float per voxel) smaller than ML_UINT32_MAX, and
enough memory to allocate the voxel field twice temporarily. A a DCMTree::Exception with appropriate text description is thrown if any of the upper facts is not fulfilled. If any of the upper facts are not fulfilled a DCMTree::Exception with appropriate text description is thrown.

Classes

Functions

Detailed Description

Function Documentation

◆ addAndSetSEGPixelDataTag()

◆ appendImagePixelModuleTags()

◆ determineFrameRegion()

◆ getSpacingImagePositionAndOrientationPatientFromMLWorldMatrix()

◆ setImagePixelTags()

◆ setPixelData()

◆ setSegmentationBinaryImagePixelTags()

◆ setSegmentationFractionalImagePixelTags()

◆ setUpPhotometricInterpretation()

◆ setVectorGridData()