MeVisLab Toolbox Reference
mlDICOMGetTools.h
Go to the documentation of this file.
1// Copyright (c) Fraunhofer MEVIS, Germany. All rights reserved.
2// **InsertLicense** code
3//----------------------------------------------------------------------------------
5
10//----------------------------------------------------------------------------------
11#pragma once
12
13#include "MLDICOMTagsSystem.h"
14
15#include <FMEThirdPartyWarningsDisable.h>
16#include <list>
17#include <set>
18#include <string>
19#include <tuple>
20#include <vector>
21#include <FMEThirdPartyWarningsRestore.h>
22
23#include <mlLinearAlgebra.h>
24#include <mlScaleShiftData.h>
25
26// DICOM Tree prototypes.
27#include <DCMTree_Lib.h>
28
29ML_START_NAMESPACE
30
31// Forwards
32class DicomMessageCollector;
33
34//----------------------------------------------------------------------------------
36//----------------------------------------------------------------------------------
37namespace DICOMTagTools {
38
42MLDICOMTags_EXPORT std::string createInstanceUID(bool useFMEUIDPrefix=false);
43
45MLDICOMTags_EXPORT bool looksLikeValidDICOMUID(const std::string &uidStrToCheck);
46
51
56MLDICOMTags_EXPORT bool looksLikeValidCSVrValue(const std::string &codedString,
57 std::string *explanation=nullptr);
58
67 const DCMTree::TagId &tagId,
68 const size_t numTagsToFind,
69 std::vector<DCMTree::Const_TagPtr> &tagVector);
70
75 const DCMTree::TagId &tagId,
76 const size_t numTagsToFind,
77 std::vector<DCMTree::TagPtr> &tagVector);
78
86 const DCMTree::TagId &tagId,
87 DCMTree::Const_TagPtr &result);
88
92 const DCMTree::TagId &tagId,
93 DCMTree::TagPtr &result);
94
95
102 const std::string &tagIdStr,
103 DCMTree::Const_TagPtr &result);
104
108 const std::string &tagIdStr,
109 DCMTree::TagPtr &result);
110
115 DCMTree::RawTagId sequenceTagId);
116
124 DCMTree::RawTagId tagId,
125 bool useNumericTagValueSorting);
126
132 DCMTree::RawTagId tagId,
133 double &ippX, double &ippY, double &ippZ,
134 double initX, double initY, double initZ);
135
141 DCMTree::RawTagId tagId,
142 double &ippX1, double &ippY1, double &ippZ1,
143 double &ippX2, double &ippY2, double &ippZ2,
144 double initX1, double initY1, double initZ1,
145 double initX2, double initY2, double initZ2);
146
157MLDICOMTags_EXPORT std::string isValidDICOMDate(std::string str,
158 bool allowEmptyStrings = true,
159 bool allowOldFormat = true);
160
168MLDICOMTags_EXPORT std::string isValidDICOMTime(const std::string &str,
169 bool allowEmptyStrings = true);
170
175MLDICOMTags_EXPORT std::pair<std::string, bool> checkDICOMPersonName(const std::string &str);
176
182 bool *isRetired=nullptr);
183
190
195
203 bool searchOnlyOnTopLevel=false);
204
208
215 double &ippX,
216 double &ippY,
217 double &ippZ,
218 bool replaceOnlyIfFound);
219
226 double &iopX1,
227 double &iopY1,
228 double &iopZ1,
229 double &iopX2,
230 double &iopY2,
231 double &iopZ2);
232
233
256
259 extern const char *const OrientationName[NumberOfOrientationTypes];
260
269 int *resultOType=nullptr);
270
275
287 bool searchRecursivly=false);
288
291 size_t *valSizeInBytes,
292 DicomMessageCollector &dcmMsgCollector);
293
298 DCMTree::Const_TagPtr &tagPtr);
299
303
310MLDICOMTags_EXPORT const boost::shared_array<unsigned char> getPixelDataFrame(DCMTree::Const_TagPtr pixTag,
311 boost::uint32_t frameIdx);
312
316
319
323
327
332
341 MLdouble &minPixVal,
342 MLdouble &maxPixVal);
343
353
363MLDICOMTags_EXPORT bool getDoubleVectorFromTag(DCMTree::Const_TagPtr tagPtr, std::vector<double> &returnDbls);
364
374
384
394
404
412 DCMTree::TagId tagId,
413 std::string *errStr=nullptr);
414
422 std::string *errStr);
423
433 const std::string &privateCreatorString);
434
455 const std::string &privateCreatorString="",
456 MLuint16 desiredPrivateGroupId=0x09,
457 MLuint8 desiredPrivateElementGroupId=0x10);
458
463 DCMTree::Const_TreePtr dcmTree);
464
474 std::string &sopUIDStr,
475 const unsigned short fmeSOPElementUID,
476 const DCMTree::RawTagId sopUID,
477 bool tryEnhancedSOPClassUIDReconstruction=false);
478
494 DCMTree::Const_TagPtr sequenceInWhichToSearch,
495 std::string &tagValuesStringListToExtend,
496 const std::string &sep,
497 std::set<std::string> *makeUniqueSet=nullptr,
498 bool searchAsLower8BitOfPrivateFMETag=false);
499
502
504MLDICOMTags_EXPORT DCMTree::Const_TagPtr getPrivateTag(const std::string &privateCreatorString,
505 unsigned short groupId,
506 DCMTree::RawTagId lowerEightBitOfElementId,
507 DCMTree::Const_TreePtr dcmTree);
508
510MLDICOMTags_EXPORT bool isPhilips3D(DCMTree::Const_TreePtr treePtr, MLint *spatialExtent=nullptr);
511
513MLDICOMTags_EXPORT unsigned int getNumberOfFrames(DCMTree::Const_TreePtr dcmTree,
514 unsigned int *fromTagOnly=nullptr);
515
533 std::string &tagValuesStringListToExtend,
534 bool alsoAddTopLevelTags,
535 const std::string &sep,
536 std::set<std::string> *makeUniqueSet=nullptr);
537
554 const std::vector<MLuint64> &rawTagIds,
555 bool appendFrameCount,
556 bool appendCoords,
557 std::list<std::vector<std::string> > &tagValuesListToExtend);
558
562 const std::vector<MLuint64> &rawTagIds,
563 std::vector<std::string> &rootEntries);
564
568
571 const std::string &modalityValue);
572
575 const std::string &errMsgSuffix=" at input 0 for Enhanced MR Image");
576
578MLDICOMTags_EXPORT std::string checkForMinMaxRangeInDataType(const double minVal,
579 const double maxVal,
580 MLDataType dType,
581 const std::string &errMsgSuffix=" at input 0");
582
586
587};
588
589ML_END_NAMESPACE
Project global and OS specific declarations.
#define MLDICOMTags_EXPORT
If included by external modules, exported symbols are declared as import symbols.
Class to wrap a tag ID.
Class to collect messages and errors related to a given frame handle.
MLint32 MLDataType
MLDataType.
Definition mlTypeDefs.h:595
unsigned char MLuint8
Definition mlTypeDefs.h:108
double MLdouble
Definition mlTypeDefs.h:216
unsigned short MLuint16
Definition mlTypeDefs.h:141
MLint64 MLint
A signed ML integer type with at least 64 bits used for index calculations on very large images even ...
Definition mlTypeDefs.h:489
boost::shared_ptr< const Tag > Const_TagPtr
Definition DCMTree_Lib.h:57
boost::shared_ptr< const StructuredMF > Const_StructuredMFPtr
boost::shared_ptr< StructuredMF > StructuredMFPtr
boost::shared_ptr< const Tree > Const_TreePtr
Definition DCMTree_Lib.h:67
boost::shared_ptr< Tag > TagPtr
Shared pointer to tag.
Definition DCMTree_Lib.h:56
std::vector< TreePtr > TreePtrVector
A vector of TreePtr - used for sequences.
Definition DCMTree_Lib.h:79
boost::shared_ptr< Tree > TreePtr
Shared pointer to a DCMTree::Tree.
Definition DCMTree_Lib.h:66
unsigned int RawTagId
MLDICOMTags_EXPORT bool 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 value...
MLDICOMTags_EXPORT bool 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 explan...
MLDICOMTags_EXPORT bool isJPEG2000Compressed(DCMTree::Const_TreePtr treePtr)
Returns true if any JPEG2000 compression was used to compress the pixel data, otherwise false.
MLDICOMTags_EXPORT void 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 ...
MLDICOMTags_EXPORT bool 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 ca...
MLDICOMTags_EXPORT bool isValidCSVrCharacter(const char ch)
Returns true if ch is a character valid of CS value representations, otherwise false (uppercase lette...
MLDICOMTags_EXPORT DCMTree::TagPtr getTagIfItExists(DCMTree::TreePtr dcmTree, DCMTree::TagId tagId, std::string *errStr=nullptr)
MLDICOMTags_EXPORT std::string 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 mes...
MLDICOMTags_EXPORT bool looksLikeValidDICOMUID(const std::string &uidStrToCheck)
Returns true if uidStrToCheck looks like a plausible valid DICOM UID, otherwise false.
MLDICOMTags_EXPORT const DCMTree::TreePtrVector * 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 sequenceTa...
MLDICOMTags_EXPORT bool isCompressed(DCMTree::Const_TreePtr treePtr)
Returns true if the DICOM tree has a transfer syntax UID which indicates compression,...
MLDICOMTags_EXPORT std::string 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 descrip...
MLDICOMTags_EXPORT unsigned int 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 ScaleShiftData getRescaleSlopeInterceptAsScaleShift(DCMTree::Const_TreePtr treePtr)
Returns a ScaleShiftData object according to rescale and slope tag values.
MLDICOMTags_EXPORT std::string checkForMultipleSeriesInstanceUIDs(DCMTree::Const_TreePtr dcmTree)
Returns an empty string if the input DCMTree has only one series in its SMF hierarchy and an error st...
MLDICOMTags_EXPORT bool getTopLevelSOPUID(DCMTree::Const_TreePtr dcmTree, std::string &sopUIDStr, const unsigned short fmeSOPElementUID, const DCMTree::RawTagId sopUID, bool tryEnhancedSOPClassUIDReconstruction=false)
Tries to get the SOP[Instance|Class]UID from top level of dcmTree:
MLDICOMTags_EXPORT bool getVector6FromTag(DCMTree::Const_TagPtr tagPtr, Vector6 &returnVec)
Converts six values of tagPtr to six Vector6 values in returnVec, respectively.
MLDICOMTags_EXPORT bool get4x4DoubleMatrixFromTag(DCMTree::Const_TagPtr tagPtr, Matrix4 &returnMat)
Converts 16 values of tagPtr to 16 double matrix values in returnMat, respectively.
MLDICOMTags_EXPORT void 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 ...
MLDICOMTags_EXPORT size_t 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,...
MLDICOMTags_EXPORT bool 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 DCMTree::TreePtr cloneDCMTree(DCMTree::Const_TreePtr dcmTree, std::string *errStr)
Create a deep-copy of the passed dcmTree as DICOM tree to be modified.
MLDICOMTags_EXPORT std::string isLossyCompressed(DCMTree::Const_TreePtr treePtr)
Returns "Yes" if the DICOM tree has a tag indicating a lossy compression, or if the tag indicates no ...
MLDICOMTags_EXPORT bool getVector3FromTag(DCMTree::Const_TagPtr tagPtr, Vector3 &returnVec)
Converts three values of tagPtr to three Vector3 values in returnVec, respectively.
MLDICOMTags_EXPORT std::string 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...
MLDICOMTags_EXPORT void 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 ...
MLDICOMTags_EXPORT bool hasNegativeSliceSpacing(DCMTree::Const_TreePtr treePtr)
Returns true if the tree has a SpacingBetweenSlices tag with a negative value.
MLDICOMTags_EXPORT size_t 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 ...
MLDICOMTags_EXPORT bool getVector2FromTag(DCMTree::Const_TagPtr tagPtr, Vector2 &returnVec)
Converts two values of tagPtr to two Vector2 values in returnVec, respectively.
MLDICOMTags_EXPORT bool 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 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 ...
MLDICOMTags_EXPORT size_t 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 returne...
MLDICOMTags_EXPORT std::string isValidDICOMTime(const std::string &str, bool allowEmptyStrings=true)
Checks whether str is a valid DICOM time string of the formats HHMM, HHMMSS, or HHMMSS....
MLDICOMTags_EXPORT std::string createInstanceUID(bool useFMEUIDPrefix=false)
Generate new IDs for DICOM frames, for example new SOPinstanceUIDs.
MLDICOMTags_EXPORT bool getDoubleFromTag(DCMTree::Const_TagPtr tagPtr, double &returnDbl)
Converts one values of tagPtr to a double values in returnDbl.
MLDICOMTags_EXPORT std::string 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...
MLDICOMTags_EXPORT void 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;...
MLDICOMTags_EXPORT DCMTree::Const_TagPtr 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 ...
OrientationType
Enumerator for typical human readable anatomic orientations.
@ LessAlmostCoronal
Less approximately Coronal.
@ NumberOfOrientationTypes
Number of available orientation modes.
@ LessAlmostSagittal
Less approximately Sagittal.
@ Axial
axial in supine position
@ LessAlmostAxial
Less approximately Axial.
@ Prone
axial in prone position
@ InvalidOrientation
Something in the orientation is not standard compliant.
@ AlmostSagittal
Approximately Sagittal.
@ NotApplicable
Orientation type makes no sense in this context.
@ OtherOrientation
A valid orientation, but non of the upper ones.
@ AlmostCoronal
Approximately Coronal.
@ AlmostAxial
Approximately Axial.
@ NoValues
No orientation values found in DICOM tree.
MLDICOMTags_EXPORT std::string 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 sto...
MLDICOMTags_EXPORT std::string getHumanReadableImageOrientationPatient(DCMTree::Const_TreePtr dcmTree, int *resultOType=nullptr)
Determine (ACR_NEMA)ImageOrientationPatient from dcmTree and create a human readable orientation from...
MLDICOMTags_EXPORT std::string 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 otherw...
MLDICOMTags_EXPORT std::string 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,...
MLDICOMTags_EXPORT unsigned int findPrivateTagGroup(DCMTree::TreePtr dcmTree, const std::string &privateCreatorString)
Determine tag ID mask of the private creator given by privateCreatorString and return it as mask 0xGG...
MLDICOMTags_EXPORT bool hasAtMostOneFrameInSMFGrid(const DCMTree::StructuredMFPtr &smfTree)
Returns true if the passed SMFTree has only one grid entry, if smfTree is nullptr or smfTree->tagTree...
MLDICOMTags_EXPORT const DCMTree::MFPixelTag * 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 pi...
MLDICOMTags_EXPORT bool isBitImageDICOM(DCMTree::Const_TreePtr treePtr)
Returns true if the DICOM pixel size seems to be single bit (indicated by appropriate values of BitsA...
MLDICOMTags_EXPORT size_t 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 retriev...
MLDICOMTags_EXPORT void 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 sequenceInWhichToSea...
MLDICOMTags_EXPORT DCMTree::Const_TagPtr getMeVisStructuredMFDimensionSequence(DCMTree::Const_TreePtr dcmTree)
Searches the structured multi-frame sequence tag on top-level in dcmTree or nullptr if not found or d...
MLDICOMTags_EXPORT std::string getTransferSyntaxUIDAsString(DCMTree::Const_TreePtr treePtr, bool searchOnlyOnTopLevel=false)
Deep search and return the value of the DICOM tag TransferSyntaxUID as string.
MLDICOMTags_EXPORT DCMTree::Const_TagPtr getPrivateFMETag(DCMTree::RawTagId lowerEightBitOfElementId, DCMTree::Const_TreePtr dcmTree)
Searches private FME tag with lower 8 bit element id lowerEightBitOfElementId with FMEPrivateTagsGrou...
MLDICOMTags_EXPORT const boost::shared_array< unsigned char > 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...
MLDICOMTags_EXPORT std::pair< std::string, bool > checkDICOMPersonName(const std::string &str)
Returns a std::pair<"", false> is empty if str looks like a valid patient name, otherwise std::pair<E...
Contains pixel data that is either shared/ref-counted or a direct pointer.
Definition DCMTree_Lib.h:99