A collection of tools related to DICOM tags and dictionaries. More...

#include "MLDICOMTagsSystem.h"
#include <FMEThirdPartyWarningsDisable.h>
#include <list>
#include <set>
#include <string>
#include <vector>
#include <FMEThirdPartyWarningsRestore.h>
#include <mlLinearAlgebra.h>
#include <mlScaleShiftData.h>
#include <DCMTree_Lib.h>

Namespaces
namespace	ml
	Main documentation file for ML users and developers.

namespace	ml::DICOMTagTools
	A namespace collecting tools related to DICOM tags and tree tools.

Enumerations
enum	ml::DICOMTagTools::OrientationType { ml::DICOMTagTools::InvalidOrientation = 0 , ml::DICOMTagTools::Axial , ml::DICOMTagTools::Prone , ml::DICOMTagTools::Cranial , ml::DICOMTagTools::Coronal , ml::DICOMTagTools::Sagittal , ml::DICOMTagTools::AlmostAxial , ml::DICOMTagTools::AlmostCoronal , ml::DICOMTagTools::AlmostSagittal , ml::DICOMTagTools::LessAlmostAxial , ml::DICOMTagTools::LessAlmostCoronal , ml::DICOMTagTools::LessAlmostSagittal , ml::DICOMTagTools::Oblique , ml::DICOMTagTools::OtherOrientation , ml::DICOMTagTools::NoValues , ml::DICOMTagTools::NotApplicable , ml::DICOMTagTools::NumberOfOrientationTypes }
	Enumerator for typical human readable anatomic orientations. More...

Functions
MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::createInstanceUID (bool useFMEUIDPrefix=false)
	Generate new IDs for DICOM frames, for example new SOPinstanceUIDs.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::looksLikeValidDICOMUID (const std::string &uidStrToCheck)
	Returns true if uidStrToCheck looks like a plausible valid DICOM UID, otherwise false.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::isValidCSVrCharacter (const char ch)
	Returns true if ch is a character valid of CS value representations, otherwise false (uppercase letters, 0-9, space, underscore, see http://dicom.nema.org/DICOM/2013/output/chtml/part05/sect_6.2.html).

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::looksLikeValidCSVrValue (const std::string &codedString, std::string *explanation=nullptr)
	Returns true if codedString looks like a string valid for a coded string , otherwise false; if explanation is passed as non-nullptr pointer then is set to an empty string if true is returned, otherwise it is set to an explanation which describes the problem why the string does not look valid.

MLDICOMTags_EXPORT void	ml::DICOMTagTools::deepSearchTags (DCMTree::Const_TreePtr treePtr, const DCMTree::TagId &tagId, const size_t numTagsToFind, std::vector< DCMTree::Const_TagPtr > &tagVector)
	Searches the first at most numTagsToFind tags with id tagId in treePtr and appends them to tagVector; the call is ignored if treePtr is nullptr.

MLDICOMTags_EXPORT void	ml::DICOMTagTools::deepSearchTags (DCMTree::TreePtr treePtr, const DCMTree::TagId &tagId, const size_t numTagsToFind, std::vector< DCMTree::TagPtr > &tagVector)
	Alternative version to deepSearchTags(DCMTree::Const_TreePtr, const DCMTree::TagId, const size_t, std::vector<DCMTree::Const_TagPtr> &) for non constant trees and tags; the call is ignored if treePtr is nullptr.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::deepSearchTag (DCMTree::Const_TreePtr treePtr, const DCMTree::TagId &tagId, DCMTree::Const_TagPtr &result)
	Searches a tag also in sequence tags and returns true if found, the tag is returned in result; the call is ignored if treePtr is nullptr.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::deepSearchTag (DCMTree::TreePtr treePtr, const DCMTree::TagId &tagId, DCMTree::TagPtr &result)
	Alternative version to deepSearchTags(DCMTree::Const_TreePtr, const DCMTree::TagId, DCMTree::Const_TagPtr &) for non constant trees and tags.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::deepSearchTag (DCMTree::Const_TreePtr treePtr, const std::string &tagIdStr, DCMTree::Const_TagPtr &result)
	Searches a tag also in sequence tags and returns true if found, the tag is returned in result.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::deepSearchTag (DCMTree::TreePtr treePtr, const std::string &tagIdStr, DCMTree::TagPtr &result)
	Alternative version to deepSearchTags(DCMTree::Const_TreePtr, const std::string &, DCMTree::Const_TagPtr &) for non constant trees and tags.

MLDICOMTags_EXPORT const DCMTree::TreePtrVector *	ml::DICOMTagTools::getSequenceItemTreePtrVector (DCMTree::Const_TreePtr dcmMFTree, DCMTree::RawTagId sequenceTagId)
	If possible it returns a pointer to the vector of sequence item (trees) of the tag with id sequenceTagId, otherwise nullptr (for example a nullptr input tree of tag not found or no sequence tag).

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::getTagValue (DCMTree::Const_TreePtr treePtr, DCMTree::RawTagId tagId, bool useNumericTagValueSorting)
	Return tag value of first tag with id tagId in the DICOM tree treePtr as string if it exists, otherwise or if treePtr is nullptr it returns an empty string.

MLDICOMTags_EXPORT size_t	ml::DICOMTagTools::getTripleTag (DCMTree::Const_TreePtr treePtr, DCMTree::RawTagId tagId, double &ippX, double &ippY, double &ippZ, double initX, double initY, double initZ)
	Returns the given DICOM tag as three double values; all values which can not be retrieved are returned as values given by the corresponding init* values.

MLDICOMTags_EXPORT size_t	ml::DICOMTagTools::getHexTag (DCMTree::Const_TreePtr treePtr, DCMTree::RawTagId tagId, double &ippX1, double &ippY1, double &ippZ1, double &ippX2, double &ippY2, double &ippZ2, double initX1, double initY1, double initZ1, double initX2, double initY2, double initZ2)
	Returns the given DICOM tag as two 3 component double vectors; all values which can not be retrieved are returned as values given by the corresponding init* values.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::isValidDICOMDate (std::string str, bool allowEmptyStrings=true, bool allowOldFormat=true)
	Checks whether str is a valid DICOM date string and returns an empty string on success or a non empty error/help string otherwise.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::isValidDICOMTime (const std::string &str, bool allowEmptyStrings=true)
	Checks whether str is a valid DICOM time string of the formats HHMM, HHMMSS, or HHMMSS.F with HH=hours, MM=minutes, SS=seconds, and F=fractional part of a second.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::getCompressionDescription (DCMTree::Const_TreePtr treePtr, bool *isRetired=nullptr)
	Returns a textual description of a compression type if it is found in the available transfer UIDs stored in this functions.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::isLossyCompressed (DCMTree::Const_TreePtr treePtr)
	Returns "Yes" if the DICOM tree has a tag indicating a lossy compression, or if the tag indicates no compression then "No" is returned.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::isCompressed (DCMTree::Const_TreePtr treePtr)
	Returns true if the DICOM tree has a transfer syntax UID which indicates compression, otherwise false.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::getTransferSyntaxUIDAsString (DCMTree::Const_TreePtr treePtr, bool searchOnlyOnTopLevel=false)
	Deep search and return the value of the DICOM tag TransferSyntaxUID as string.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::isJPEG2000Compressed (DCMTree::Const_TreePtr treePtr)
	Returns true if any JPEG2000 compression was used to compress the pixel data, otherwise false.

MLDICOMTags_EXPORT size_t	ml::DICOMTagTools::getImagePositionPatient (DCMTree::Const_TreePtr treePtr, double &ippX, double &ippY, double &ippZ, bool replaceOnlyIfFound)
	Return the DICOM tag ImagePositionPatient as three double values; all values which can not be retrieved are returned as 0.

MLDICOMTags_EXPORT size_t	ml::DICOMTagTools::getImageOrientationPatient (DCMTree::Const_TreePtr treePtr, double &iopX1, double &iopY1, double &iopZ1, double &iopX2, double &iopY2, double &iopZ2)
	Return the DICOM tag ImageOrientationPatient as two 3D vectors (iopX1, iopY1, iopZ1) and (iopX2, iopY2, iopZ2); all values which can not be retrieved are returned as from the corresponding components from (X1,Y1,Z1)=(1,0,0) and (X2,Y2,Z2)=(0,1,0).

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::getHumanReadableImageOrientationPatient (DCMTree::Const_TreePtr dcmTree, int *resultOType=nullptr)
	Determine (ACR_NEMA)ImageOrientationPatient from dcmTree and create a human readable orientation from it with additional error information if necessary.

MLDICOMTags_EXPORT ScaleShiftData	ml::DICOMTagTools::getRescaleSlopeInterceptAsScaleShift (DCMTree::Const_TreePtr treePtr)
	Returns a ScaleShiftData object according to rescale and slope tag values.

MLDICOMTags_EXPORT DCMTree::Const_TagPtr	ml::DICOMTagTools::getAnyPixelDataTag (DCMTree::Const_TreePtr treePtr, bool searchRecursivly=false)
	Searches and returns the first pixel data pointer on top level found in treePtr, or a nil tag if not found.

MLDICOMTags_EXPORT DCMTree::PixelData	ml::DICOMTagTools::getPixelDataPtrFromTree (DCMTree::Const_TreePtr treePtr, size_t *valSizeInBytes, DicomMessageCollector &dcmMsgCollector)
	Same as DICOMCachedIOTools::getPixelDataPtrFromTree().

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::hasMFPixelDataTag (DCMTree::Const_TreePtr treePtr, DCMTree::Const_TagPtr &tagPtr)
	Returns true if the tree has a multi-frame pixel data tag containing many frames or false otherwise.

MLDICOMTags_EXPORT const DCMTree::MFPixelTag *	ml::DICOMTagTools::getAsMFPixelPtr (DCMTree::Const_TagPtr tag)
	Returns a pointer to the correctly cast multi-frame class type of tag if it is a valid multi-frame pixel data tag; in all other cases it returns nullptr.

MLDICOMTags_EXPORT const boost::shared_array< unsigned char >	ml::DICOMTagTools::getPixelDataFrame (DCMTree::Const_TagPtr pixTag, boost::uint32_t frameIdx)
	Returns a memory copy of the frame at index position frameIdx of the pixel data tag pixTag or nullptr if it is not such tag, the frameIdx is out of range or any other error.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::usesNegativeNMStacking (DCMTree::Const_TreePtr treePtr)
	Returns true if the tree has tags which indicate that it is NM data and the pixel data is stacked in inverse order and has an MFPixelDataTag.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::hasNegativeSliceSpacing (DCMTree::Const_TreePtr treePtr)
	Returns true if the tree has a SpacingBetweenSlices tag with a negative value.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::hasAtMostOneFrameInSMFGrid (const DCMTree::StructuredMFPtr &smfTree)
	Returns true if the passed SMFTree has only one grid entry, if smfTree is nullptr or smfTree->tagTree is nullptr.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::hasAtMostOneFrameInSMFGrid (const DCMTree::Const_StructuredMFPtr &smfTree)
	Returns true if the passed constant SMFTree has only one grid entry, if smfTree is nullptr or smfTree->tagTree is nullptr.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::isBitImageDICOM (DCMTree::Const_TreePtr treePtr)
	Returns true if the DICOM pixel size seems to be single bit (indicated by appropriate values of BitsAllocated, Stored and highBit), otherwise false.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::updateMinMaxFromDICOMTags (DCMTree::Const_TreePtr treePtr, MLdouble &minPixVal, MLdouble &maxPixVal)
	Checks for min/max DICOM tags on top level and - if both are found - updates the passed min/max values.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::getDoubleFromTag (DCMTree::Const_TagPtr tagPtr, double &returnDbl)
	Converts one values of tagPtr to a double values in returnDbl.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::getDoubleVectorFromTag (DCMTree::Const_TagPtr tagPtr, std::vector< double > &returnDbls)
	Converts all values of tagPtr to a std::vector of doubles in returnDbls.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::getVector2FromTag (DCMTree::Const_TagPtr tagPtr, Vector2 &returnVec)
	Converts two values of tagPtr to two Vector2 values in returnVec, respectively.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::getVector3FromTag (DCMTree::Const_TagPtr tagPtr, Vector3 &returnVec)
	Converts three values of tagPtr to three Vector3 values in returnVec, respectively.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::getVector6FromTag (DCMTree::Const_TagPtr tagPtr, Vector6 &returnVec)
	Converts six values of tagPtr to six Vector6 values in returnVec, respectively.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::get4x4DoubleMatrixFromTag (DCMTree::Const_TagPtr tagPtr, Matrix4 &returnMat)
	Converts 16 values of tagPtr to 16 double matrix values in returnMat, respectively.

MLDICOMTags_EXPORT DCMTree::TagPtr	ml::DICOMTagTools::getTagIfItExists (DCMTree::TreePtr dcmTree, DCMTree::TagId tagId, std::string *errStr=nullptr)

MLDICOMTags_EXPORT DCMTree::TreePtr	ml::DICOMTagTools::cloneDCMTree (DCMTree::Const_TreePtr dcmTree, std::string *errStr)
	Create a deep-copy of the passed dcmTree as DICOM tree to be modified.

MLDICOMTags_EXPORT unsigned int	ml::DICOMTagTools::findPrivateTagGroup (DCMTree::TreePtr dcmTree, const std::string &privateCreatorString)
	Determine tag ID mask of the private creator given by privateCreatorString and return it as mask 0xGGGGPP00 where GGGG is the private creator group id and PP the lower eight bit defining the upper eight bits of added private tags.

MLDICOMTags_EXPORT unsigned int	ml::DICOMTagTools::searchPrivateCreator (DCMTree::TreePtr dcmTree, const std::string &privateCreatorString="", MLuint16 desiredPrivateGroupId=0x09, MLuint8 desiredPrivateElementGroupId=0x10)
	Determine the first odd group id with private element group id.

MLDICOMTags_EXPORT DCMTree::Const_TagPtr	ml::DICOMTagTools::getPrivateFMETag (DCMTree::RawTagId lowerEightBitOfElementId, DCMTree::Const_TreePtr dcmTree)
	Searches private FME tag with lower 8 bit element id lowerEightBitOfElementId with FMEPrivateTagsGroupId and FMEPrivateCreatorString in dcmTree and returns the tag if possible, otherwise (if dcmTree is nullptr, not found, no slot etc.) it returns nullptr.

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::getTopLevelSOPInstanceUID (DCMTree::Const_TreePtr dcmTree, std::string &sopInstanceUID)
	Get the original SOPInstanceUID from top level of dcmTree, returns the value in sopInstanceUID and return true if the value looks valid; for this purpose prefer FMEPrivateSourceSOPInstanceUIDOfDecomposedFrame since it stores the original one and not a possibly recreated one.

MLDICOMTags_EXPORT void	ml::DICOMTagTools::getTagStringValuesFromSequence (DCMTree::RawTagId rawTagId, DCMTree::Const_TagPtr sequenceInWhichToSearch, std::string &tagValuesStringListToExtend, const std::string &sep, std::set< std::string > *makeUniqueSet=nullptr, bool searchAsLower8BitOfPrivateFMETag=false)
	Deep-searches all occurrences of the tag with id tagToSearch in the sequence tag sequenceInWhichToSearch and appends all string-converted values separated by sep to tagValuesStringListToExtend.

MLDICOMTags_EXPORT DCMTree::Const_TagPtr	ml::DICOMTagTools::getMeVisStructuredMFDimensionSequence (DCMTree::Const_TreePtr dcmTree)
	Searches the structured multi-frame sequence tag on top-level in dcmTree or nullptr if not found or dcmTree is nullptr.

MLDICOMTags_EXPORT DCMTree::Const_TagPtr	ml::DICOMTagTools::getPrivateTag (const std::string &privateCreatorString, unsigned short groupId, DCMTree::RawTagId lowerEightBitOfElementId, DCMTree::Const_TreePtr dcmTree)
	See DICOMCachedIOTools::getPrivateTag().

MLDICOMTags_EXPORT bool	ml::DICOMTagTools::isPhilips3D (DCMTree::Const_TreePtr treePtr, MLint *spatialExtent=nullptr)
	See DICOMCachedIOTools::isPhilips3D().

MLDICOMTags_EXPORT unsigned int	ml::DICOMTagTools::getNumberOfFrames (DCMTree::Const_TreePtr dcmTree, unsigned int *fromTagOnly=nullptr)
	See DICOMCachedIOTools::getNumberOfFrames().

MLDICOMTags_EXPORT void	ml::DICOMTagTools::extractTagValuesFromPerFrameAndMeVisMFSequence (DCMTree::RawTagId rawTagId, DCMTree::Const_TreePtr dcmTree, std::string &tagValuesStringListToExtend, bool alsoAddTopLevelTags, const std::string &sep, std::set< std::string > *makeUniqueSet=nullptr)
	Looks for frame-specific tags with ID rawTagId in sequences DCMTree_PerFrameFunctionalGroupsSequence and getMeVisStructuredMFDimensionSequence of dcmTree and if they are found they are appended to tagValuesStringListToExtend, separated with sep.

MLDICOMTags_EXPORT void	ml::DICOMTagTools::getTagStringValuesFromSMFSequence (DCMTree::Const_TreePtr inputDcmTree, const std::vector< MLuint64 > &rawTagIds, bool appendFrameCount, bool appendCoords, std::list< std::vector< std::string > > &tagValuesListToExtend)
	Looks for frame-specific tags rawTagIds in getMeVisStructuredMFDimensionSequence of inputDcmTree and if they are found they are appended to tagValuesStringListToExtend.

MLDICOMTags_EXPORT void	ml::DICOMTagTools::getTagStringValuesFromTopLevel (DCMTree::Const_TreePtr inputDcmTree, const std::vector< MLuint64 > &rawTagIds, std::vector< std::string > &rootEntries)
	Like getTagStringValuesFromSMFSequence() but retrieves tags only from top level of inputDcmTree into cleared rootEntries; coordinate entries are not appended to rootEntries.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::checkForMultipleSeriesInstanceUIDs (DCMTree::Const_TreePtr dcmTree)
	Returns an empty string if the input DCMTree has only one series in its SMF hierarchy and an error string otherwise.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::checkForExpectedModality (DCMTree::Const_TreePtr inTree, const std::string &modalityValue)
	Returns an empty string if the input DCMTree has the modality modalityValue or an error string otherwise.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::checkFor8Or16BitIntType (MLDataType dType, const std::string &errMsgSuffix=" at input 0 for Enhanced MR Image")
	Returns an empty string if dType is of an 8 or 16 bit integer type, otherwise a descriptive error message + msgSuffix.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::checkForMinMaxRangeInDataType (const double minVal, const double maxVal, MLDataType dType, const std::string &errMsgSuffix=" at input 0")
	Returns an empty string if minVal and maxVal are inside range of given data type, otherwise a descriptive error message + msgSuffix.

MLDICOMTags_EXPORT std::string	ml::DICOMTagTools::checkFor32BitRangedInputImage (const ImageVector &inImgExt, MLDataType dType)
	Returns an empty string if inImgExt is not zero and does not exceed 32 bit range even when allocating it with large dType; otherwise a descriptive error message.

Variables
const char *const	ml::DICOMTagTools::OrientationName [NumberOfOrientationTypes]
	String representations analog to the OrientationType, however, NumberOfOrientationTypes is out of range.

Detailed Description

A collection of tools related to DICOM tags and dictionaries.

Author: Wolf Spindler.

Date: 07/2013

Definition in file mlDICOMGetTools.h.

Namespaces

Enumerations

Functions

Variables

Detailed Description