From: jpr Date: Sun, 23 Oct 2005 15:32:30 +0000 (+0000) Subject: Minor Doxygenations, comments fixing, etc X-Git-Tag: OpenJPEG.Version1.2~226 X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?a=commitdiff_plain;h=cb6cf86b2b3cc6b43d40561fb9552ebd19fdbc99;p=gdcm.git Minor Doxygenations, comments fixing, etc --- diff --git a/src/gdcmBase.h b/src/gdcmBase.h index a74e7694..8d88bf50 100644 --- a/src/gdcmBase.h +++ b/src/gdcmBase.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmBase.h,v $ Language: C++ - Date: $Date: 2005/10/21 07:40:13 $ - Version: $Revision: 1.9 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.10 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -26,7 +26,7 @@ namespace gdcm { //----------------------------------------------------------------------------- /** - * \brief Base class of all gdcm classes + * \brief Base class of all gdcm classes. * Contains the Print related methods : * - Print * - SetPrintLevel / GetPrintLevel @@ -34,9 +34,11 @@ namespace gdcm class GDCM_EXPORT Base { public: + /// \brief Constructor Base( ) {PrintLevel = 0;} + /// \brief Canonical Destructor virtual ~Base() {} - + /// \brief Printer virtual void Print(std::ostream & = std::cout, std::string const & = "" ) {}; diff --git a/src/gdcmCommon.h b/src/gdcmCommon.h index 1361a754..fa971dc5 100644 --- a/src/gdcmCommon.h +++ b/src/gdcmCommon.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmCommon.h,v $ Language: C++ - Date: $Date: 2005/10/20 15:24:08 $ - Version: $Revision: 1.100 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.101 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -129,9 +129,9 @@ enum LodModeType */ struct DicomElement { - /// DicomGroup number + /// Dicom Group number unsigned short int Group; - /// DicomElement number + /// Dicom Element number unsigned short int Elem; /// value (coded as a std::string) of the Element std::string Value; diff --git a/src/gdcmDataEntry.cxx b/src/gdcmDataEntry.cxx index 4d7b7628..fbd95c44 100644 --- a/src/gdcmDataEntry.cxx +++ b/src/gdcmDataEntry.cxx @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDataEntry.cxx,v $ Language: C++ - Date: $Date: 2005/10/21 15:52:13 $ - Version: $Revision: 1.9 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.10 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -86,7 +86,9 @@ void DataEntry::SetBinArea( uint8_t *area, bool self ) State = STATE_LOADED; } - +/** + * \brief Inserts the value (non string) into the current Dicom Header Entry + */ void DataEntry::CopyBinArea( uint8_t *area, uint32_t length ) { DeleteBinArea(); @@ -105,7 +107,7 @@ void DataEntry::CopyBinArea( uint8_t *area, uint32_t length ) } } -void DataEntry::SetValue(const uint32_t &id,const double &val) +void DataEntry::SetValue(const uint32_t &id, const double &val) { if( !BinArea ) NewBinArea(); @@ -147,22 +149,30 @@ void DataEntry::SetValue(const uint32_t &id,const double &val) BinArea[id] = (uint8_t)val; } } - +/** + * \brief returns, as a double (?!?) one of the values + // (when entry is multivaluated), identified by its index. + // Returns 0.0 if index is wrong + // FIXME : warn the user there was a problem ! + */ double DataEntry::GetValue(const uint32_t &id) const { if( !BinArea ) { gdcmErrorMacro("BinArea not set. Can't get the value"); - return 0; + return 0.0; } uint32_t count = GetValueCount(); if( id > count ) { gdcmErrorMacro("Index (" << id << ")is greater than the data size"); - return 0; + return 0.0; } + // FIX the API : user *knows* that entry contains a US + // and he receives a double ?!? + const VRKey &vr = GetVR(); if( vr == "US" || vr == "SS" ) return ((uint16_t *)BinArea)[id]; @@ -219,31 +229,55 @@ double DataEntry::GetValue(const uint32_t &id) const return BinArea[id]; } +/** + * \brief Checks if the multiplicity of the value follows Dictionary VM + */ bool DataEntry::IsValueCountValid() const { bool valid = false; uint32_t vm; const std::string &strVM = GetVM(); uint32_t vc = GetValueCount(); + + // FIXME : what shall we do with VM = "2-n", "3-n", etc + if( strVM == "1-n" ) - { + { // make sure it is at least one ??? FIXME valid = vc >= 1 || vc == 0; - } + } else - { + { std::istringstream os; os.str( strVM ); os >> vm; // Two cases: // vm respect the one from the dict - // vm is 0 (we need to check is this element is allowed to be empty) FIXME + // vm is 0 (we need to check if this element is allowed to be empty) FIXME + + // note (JPR) + // ---- + // Entries whose type is 1 are mandatory, with a mandatory value. + // Entries whose type is 1c are mandatory-inside-a-Sequence, + // with a mandatory value. + // Entries whose type is 2 are mandatory, with an optional value. + // Entries whose type is 2c are mandatory-inside-a-Sequence, + // with an optional value. + // Entries whose type is 3 are optional. + + // case vc == 0 is only applicable for 'type 2' entries. + // Problem : entry type may depend on the modality and/or the Sequence + // it's embedded in ! + // (Get the information in the 'Conformance Statements' ...) valid = vc == vm || vc == 0; - } + } return valid; } -uint32_t DataEntry::GetValueCount(void) const +/** + * \brief returns the number of elementary values + */ +uint32_t DataEntry::GetValueCount( ) const { const VRKey &vr = GetVR(); if( vr == "US" || vr == "SS" ) @@ -270,7 +304,10 @@ uint32_t DataEntry::GetValueCount(void) const return GetLength(); } - +/** + * \brief Sets the 'value' of an Entry, passed as a std::string + * @param value string representation of the value to be set + */ void DataEntry::SetString(std::string const &value) { DeleteBinArea(); @@ -328,16 +365,30 @@ void DataEntry::SetString(std::string const &value) { if( value.size() > 0 ) { + // FIXME : should be quicker if we don't create one more std::string + // just to make even the length of a char array ... + + /* std::string finalVal = Util::DicomString( value.c_str() ); SetLength(finalVal.size()); NewBinArea(); memcpy(BinArea, &(finalVal[0]), finalVal.size()); + */ + + size_t l = value.size(); + SetLength(l + l%2); + NewBinArea(); + memcpy(BinArea, &(value[0]), l); + if (l%2) + BinArea[l] = '\0'; } } State = STATE_LOADED; } - +/** + * \brief returns as a string (when possible) the value of the DataEntry + */ std::string const &DataEntry::GetString() const { static std::ostringstream s; @@ -348,6 +399,9 @@ std::string const &DataEntry::GetString() const if( !BinArea ) return StrArea; + + // When short integer(s) are stored, convert the following (n * 2) characters + // as a displayable string, the values being separated by a back-slash if( vr == "US" || vr == "SS" ) { @@ -361,7 +415,7 @@ std::string const &DataEntry::GetString() const } StrArea=s.str(); } - // See above comment on multiple integers (mutatis mutandis). + // See above comment on multiple short integers (mutatis mutandis). else if( vr == "UL" || vr == "SL" ) { uint32_t *data=(uint32_t *)BinArea; @@ -403,7 +457,10 @@ std::string const &DataEntry::GetString() const return StrArea; } - +/** + * \brief Copies all the attributes from an other DocEntry + * @param doc entry to copy from + */ void DataEntry::Copy(DocEntry *doc) { DocEntry::Copy(doc); @@ -416,7 +473,11 @@ void DataEntry::Copy(DocEntry *doc) CopyBinArea(entry->BinArea,entry->GetLength()); } } - +/** + * \brief Writes the value of a DataEntry + * @param fp already open ofstream pointer + * @param filetype type of the file (ACR, ImplicitVR, ExplicitVR, ...) + */ void DataEntry::WriteContent(std::ofstream *fp, FileType filetype) { DocEntry::WriteContent(fp, filetype); @@ -553,10 +614,15 @@ void DataEntry::Print(std::ostream &os, std::string const & ) { if(Global::GetVR()->IsVROfStringRepresentable(vr)) { - std::string cleanString = Util::CreateCleanString(v); // replace non printable characters by '.' + // replace non printable characters by '.' + std::string cleanString = Util::CreateCleanString(v); if ( cleanString.length() <= GetMaxSizePrintEntry() - || PrintLevel >= 3 - || IsNotLoaded() ) + || PrintLevel >= 3 + || IsNotLoaded() ) + // FIXME : when IsNotLoaded(), you create a Clean String ?!? + // FIXME : PrintLevel<2 *does* print the values + // (3 is only for extra offsets printing) + // What do you wanted to do ? JPR { s << " [" << cleanString << "]"; } @@ -567,8 +633,14 @@ void DataEntry::Print(std::ostream &os, std::string const & ) } else { - if ( Util::IsCleanArea( GetBinArea(),GetLength() ) ) + // A lot of Private elements (with no VR) contain actually + // only printable characters; + // Let's deal with them as is they were VR std::string representable + + if ( Util::IsCleanArea( GetBinArea(), GetLength() ) ) { + // FIXME : since the 'Area' *is* clean, just use + // a 'CreateString' method, to save CPU time. std::string cleanString = Util::CreateCleanString( BinArea,GetLength() ); s << " [" << cleanString << "]"; diff --git a/src/gdcmDataEntry.h b/src/gdcmDataEntry.h index 7bd59830..f8882df9 100644 --- a/src/gdcmDataEntry.h +++ b/src/gdcmDataEntry.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDataEntry.h,v $ Language: C++ - Date: $Date: 2005/10/21 14:09:41 $ - Version: $Revision: 1.3 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.4 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -27,7 +27,7 @@ namespace gdcm { //----------------------------------------------------------------------------- /** - * \brief Any Dicom Document (File or DicomDir) contains + * \brief Any Dicom Document (File or DicomDir, or ...) contains * a set of DocEntry - Dicom entries - * (when successfuly parsed against a given Dicom dictionary) * DataEntry is an elementary DocEntry (as opposed to SeqEntry). @@ -46,7 +46,7 @@ public: // Write virtual void WriteContent(std::ofstream *fp, FileType filetype); -// Set/Get datas +// Set/Get data /// Sets the value (string) of the current Dicom entry //virtual void SetValue(std::string const &val); /// \brief Returns the 'Value' (e.g. "Dupond^Marcel") converted @@ -70,20 +70,27 @@ public: /// \brief Sets SelfArea void SetSelfArea(bool area) { SelfArea = area; } - /// \brief Returns SelfArea + /// \brief True if Entry owns its BinArea bool IsSelfArea() { return SelfArea; } // State void SetState(const char &state) { State = state; } const char &GetState() const { return State; } + /// \brief true when value Entry not loaded bool IsNotLoaded() { return State == STATE_NOTLOADED; } + /// \brief true if Entry not found bool IsUnfound() { return State == STATE_UNFOUND; } + /// \brief true if Entry not read bool IsUnread() { return State == STATE_UNREAD; } + /// \brief true if Entry value properly loaded bool IsGoodValue() { return State == 0; } // Flags + /// \brief sets the 'pixel data flag' void SetFlag(const char &flag) { Flag = flag; } + /// \brief returns the 'pixel data flag' const char &GetFlag() const { return Flag; } + /// \brief true id Entry is a Pixel Data entry bool IsPixelData() { return (Flag & FLAG_PIXELDATA) != 0; } void Copy(DocEntry *doc); @@ -94,6 +101,7 @@ public: /// \brief Header Elements too long will not be printed static void SetMaxSizePrintEntry(const uint32_t &size) { MaxSizePrintEntry = size; } + ///\brief values for current state of a DataEntry (internal use only) typedef enum { STATE_LOADED = 0x00, @@ -101,7 +109,8 @@ public: STATE_UNFOUND = 0x02, STATE_UNREAD = 0x03 } TValueState; - + + ///\brief values for current pixel status of a DataEntry (internal use only) typedef enum { FLAG_NONE = 0x00, @@ -119,11 +128,14 @@ protected: uint8_t *BinArea; /// \brief Whether DataEntry has its own BinArea or not bool SelfArea; - + /// \brief std::string representable value of the Entry. + /// Parts of a multivaluated data are separated by back-slash mutable std::string StrArea; private: + /// \brief 0 for straight entries, FLAG_PIXELDATA for Pixel Data entries char Flag; + /// \brief Entry status : STATE_NOTLOADED,STATE_UNFOUND, STATE_UNREAD, 0 char State; /// \brief Size threshold above which an element val diff --git a/src/gdcmDicomEntry.h b/src/gdcmDicomEntry.h index 1af59fcb..dca0d819 100644 --- a/src/gdcmDicomEntry.h +++ b/src/gdcmDicomEntry.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDicomEntry.h,v $ Language: C++ - Date: $Date: 2005/10/21 15:34:56 $ - Version: $Revision: 1.6 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.7 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -29,11 +29,12 @@ namespace gdcm //----------------------------------------------------------------------------- /** * \brief - * the DicomEntry in an element contained by the Dict. + * a DicomEntry is an element contained by the Dict. * It contains : - * - the key referenced by the DICOM norm or the constructor (for private keys) - * i.e. the Group number - * the Element number + * - the key referenced by the DICOM norm or the manufacturer(for private keys) + * i.e. + * - - the Group number + * - - the Element number * - the VR (Value Representation) * - the VM (Value Multiplicity) * - the corresponding name in english @@ -75,13 +76,13 @@ protected: ~DicomEntry(); private: - /// Dicom \ref TagKey. Contains DicomGroup number and DicomElement number + /// Dicom \ref TagKey. Contains Dicom Group number and Dicom Element number TagKey Tag; /// \brief Value Representation i.e. some clue about the nature /// of the data represented e.g. - /// "FD" short for "Floating Point Double"(see \ref VR) - /// "PN" short for "Person Name" + /// - "FD" short for "Floating Point Double"(see \ref VR) + /// - "PN" short for "Person Name" VRKey VR; }; } // end namespace gdcm diff --git a/src/gdcmDict.cxx b/src/gdcmDict.cxx index b01a84f6..845114d2 100644 --- a/src/gdcmDict.cxx +++ b/src/gdcmDict.cxx @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDict.cxx,v $ Language: C++ - Date: $Date: 2005/10/20 15:24:08 $ - Version: $Revision: 1.81 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.82 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -74,7 +74,7 @@ Dict::~Dict() // Public /** - * \brief Add a all the entries held in a source dictionary + * \brief Add all the entries held in a source dictionary * \note it concerns only Private Dictionnary * @param filename from which to build the dictionary. */ @@ -222,7 +222,7 @@ void Dict::ClearEntry() /** * \brief Get the dictionary entry identified by a given tag ("group|element") - * @param key tag of the entry to be found + * @param key tag of the searched entry * @return the corresponding dictionary entry when existing, NULL otherwise */ DictEntry *Dict::GetEntry(TagKey const &key) @@ -234,7 +234,12 @@ DictEntry *Dict::GetEntry(TagKey const &key) } return it->second; } - +/** + * \brief Get the dictionary entry identified by it's "group" and "element") + * @param group Group number of the searched entry. + * @param elem Element number of the searched entry. + * @return the corresponding dictionary entry when existing, NULL otherwise + */ DictEntry *Dict::GetEntry(uint16_t group, uint16_t elem) { TagKey key = DictEntry::TranslateToKey(group, elem); diff --git a/src/gdcmDict.h b/src/gdcmDict.h index 455afd0d..d48b9694 100644 --- a/src/gdcmDict.h +++ b/src/gdcmDict.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDict.h,v $ Language: C++ - Date: $Date: 2005/10/20 15:24:08 $ - Version: $Revision: 1.43 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.44 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -78,6 +78,7 @@ private: /// Access through TagKey TagKeyHT KeyHt; + /// Iterator for the entries TagKeyHT::iterator ItKeyHt; }; } // end namespace gdcm diff --git a/src/gdcmDictGroupName.cxx b/src/gdcmDictGroupName.cxx index 15ae5cc3..66194b34 100644 --- a/src/gdcmDictGroupName.cxx +++ b/src/gdcmDictGroupName.cxx @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDictGroupName.cxx,v $ Language: C++ - Date: $Date: 2005/06/24 10:55:58 $ - Version: $Revision: 1.4 $ + Date: $Date: 2005/10/23 15:32:30 $ + Version: $Revision: 1.5 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -80,6 +80,7 @@ DictGroupName::~DictGroupName() //----------------------------------------------------------------------------- // Public +/// \returns the formerly NIH defined ACR-NEMA group name const TagName &DictGroupName::GetName(uint16_t group) { DictGroupNameHT::const_iterator it = groupName.find(group); diff --git a/src/gdcmDictGroupName.h b/src/gdcmDictGroupName.h index b57ed427..b03c5c61 100644 --- a/src/gdcmDictGroupName.h +++ b/src/gdcmDictGroupName.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDictGroupName.h,v $ Language: C++ - Date: $Date: 2005/04/06 12:49:27 $ - Version: $Revision: 1.2 $ + Date: $Date: 2005/10/23 15:32:31 $ + Version: $Revision: 1.3 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -33,8 +33,8 @@ typedef std::map DictGroupNameHT; //----------------------------------------------------------------------------- /** - * \brief Container for dicom Value Representation Hash Table - * \note This is a singleton + * \brief Container for dicom 'Value Representation' Hash Table. + * \note This is a singleton. */ class GDCM_EXPORT DictGroupName { diff --git a/src/gdcmDictSet.h b/src/gdcmDictSet.h index 237bbe80..4ae5d721 100644 --- a/src/gdcmDictSet.h +++ b/src/gdcmDictSet.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDictSet.h,v $ Language: C++ - Date: $Date: 2005/10/20 15:24:09 $ - Version: $Revision: 1.47 $ + Date: $Date: 2005/10/23 15:32:31 $ + Version: $Revision: 1.48 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -73,6 +73,7 @@ protected: private: /// Hash table of all dictionaries contained in this DictSet DictSetHT Dicts; + /// Iterator to visit the Dictionaries of a given DictSet DictSetHT::iterator ItDictHt; /// Directory path to dictionaries diff --git a/src/gdcmDirList.h b/src/gdcmDirList.h index 7eabc36e..aa64c452 100644 --- a/src/gdcmDirList.h +++ b/src/gdcmDirList.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDirList.h,v $ Language: C++ - Date: $Date: 2005/09/02 07:10:03 $ - Version: $Revision: 1.25 $ + Date: $Date: 2005/10/23 15:32:31 $ + Version: $Revision: 1.26 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -36,8 +36,8 @@ typedef std::vector DirListType; // so GDCM_EXPORT keyword was removed for this class only /** - * \brief List containing the file headers of all the gdcm readable files - * found by exploring recursively a root directory. + * \brief List containing the file headers of all the 'gdcm readable' files + * found by exploring (possibely recursively) a root directory. */ class GDCM_EXPORT DirList { diff --git a/src/gdcmDocEntry.h b/src/gdcmDocEntry.h index acd1eb73..6791b02e 100644 --- a/src/gdcmDocEntry.h +++ b/src/gdcmDocEntry.h @@ -3,8 +3,8 @@ Program: gdcm Module: $RCSfile: gdcmDocEntry.h,v $ Language: C++ - Date: $Date: 2005/10/20 15:24:09 $ - Version: $Revision: 1.53 $ + Date: $Date: 2005/10/23 15:32:31 $ + Version: $Revision: 1.54 $ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de l'Image). All rights reserved. See Doc/License.txt or @@ -66,7 +66,7 @@ public: /// Dictionnary, of the current Dicom entry VRKey const &GetVR() const { return DicomDict->GetVR(); } - /// \brief Returns the 'Value Multiplicity' (e.g. "1", "1-n", "6"), + /// \brief Returns the 'Value Multiplicity' (e.g. "1", 6", "1-n", "3-n"), /// found in the Dicom entry or in the Dicom Dictionnary /// of the current Dicom entry std::string const &GetVM() const { return DicomDict->GetVM(); }