]> Creatis software - gdcm.git/blob - gdcmDocument.h
76ed0956d54dd1c66fd2e56723a7b7259274b979
[gdcm.git] / gdcmDocument.h
1 /*=========================================================================
2  
3   Program:   gdcm
4   Module:    $RCSfile: gdcmDocument.h,v $
5   Language:  C++
6   Date:      $Date: 2005/11/21 16:28:06 $
7   Version:   $Revision: 1.136 $
8  
9   Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de
10   l'Image). All rights reserved. See Doc/License.txt or
11   http://www.creatis.insa-lyon.fr/Public/Gdcm/License.html for details.
12  
13      This software is distributed WITHOUT ANY WARRANTY; without even
14      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15      PURPOSE.  See the above copyright notices for more information.
16  
17 =========================================================================*/
18
19 #ifndef GDCMDOCUMENT_H
20 #define GDCMDOCUMENT_H
21
22 #include "gdcmVR.h"
23 #include "gdcmDict.h"
24 #include "gdcmElementSet.h"
25 #include "gdcmException.h"
26 #include "gdcmDebug.h"  // for LEGACY
27
28 #include <map>
29 #include <list>
30 #include <fstream>
31
32 namespace gdcm 
33 {
34 class SeqEntry;
35 class Dict;
36
37 //-----------------------------------------------------------------------------
38 /**
39  * \brief Derived by both gdcm::File and gdcm::DicomDir
40  */
41 class GDCM_EXPORT Document : public ElementSet
42 {
43    gdcmTypeMacro(Document);
44
45 public:
46    typedef std::list<DicomElement> ListElements;
47
48 // Loading
49    //Deprecated : use SetFileName() + Load()
50    //GDCM_LEGACY(  virtual bool Load( std::string const &filename )  ); 
51    //virtual bool Load( std::string const &filename );
52    virtual bool Load( ); 
53
54 // Dictionaries
55    Dict *GetPubDict();
56    Dict *GetShaDict();
57    bool SetShaDict(Dict *dict);
58    bool SetShaDict(DictKey const &dictName);
59
60 // Informations contained in the gdcm::Document
61    bool IsParsable();
62    virtual bool IsReadable();
63    bool IsDicomV3();
64    bool IsPapyrus();
65    FileType GetFileType();
66    std::string GetTransferSyntax();
67    /// Return the Transfer Syntax as a string
68    std::string GetTransferSyntaxName();
69
70 // Swap code
71    /// 'Swap code' accessor (see \ref SwapCode )
72    int GetSwapCode() { return SwapCode; }
73    
74 // File I/O
75    /// Accessor to \ref Filename
76    const std::string &GetFileName() const { return Filename; }
77    /// Accessor to \ref Filename
78    virtual void SetFileName(std::string const &fileName) 
79                    { if (Filename != fileName)
80                         Filename = fileName, IsDocumentModified = true; }
81
82    std::ifstream *OpenFile();
83    bool CloseFile();
84    void WriteContent( std::ofstream *fp, FileType type );
85
86 // Content entries
87    virtual void LoadEntryBinArea(uint16_t group, uint16_t elem);
88    virtual void LoadEntryBinArea(DataEntry *entry);
89
90    void LoadDocEntrySafe(DocEntry *entry);
91    void AddForceLoadElement(uint16_t group, uint16_t elem);
92  
93 // Ordering of Documents
94    bool operator<(Document &document);
95
96 /**
97  * \brief Sets the LoadMode as a boolean string. 
98  *        LD_NOSEQ, LD_NOSHADOW, LD_NOSHADOWSEQ
99  ... (nothing more, right now)
100  *        WARNING : before using NO_SHADOW, be sure *all* your files
101  *        contain accurate values in the 0x0000 element (if any) 
102  *        of *each* Shadow Group. The parser will fail if the size is wrong !
103  * @param   mode Load mode to be used    
104  */
105    void SetLoadMode (int mode) { if (LoadMode != mode) 
106                                      LoadMode=mode, IsDocumentModified = true; }
107
108 protected:
109 // Methods
110    // Constructor and destructor are protected to forbid end user 
111    // to instanciate from this class Document (only gdcm::File and
112    // gdcm::DicomDir are meaningfull).
113    Document();
114    virtual ~Document();
115    
116    uint16_t ReadInt16() throw ( FormatError );
117    uint32_t ReadInt32() throw ( FormatError );
118    void     SkipBytes(uint32_t);
119    int ComputeGroup0002Length( );
120
121 // Variables
122    /// Refering underlying filename.
123    std::string Filename;
124
125    /// \brief Swap code gives an information on the byte order of a 
126    ///  supposed to be an int32, as it's read on disc 
127    /// (depending on the image Transfer Syntax *and* on the processor endianess)
128    /// as opposed as it should in memory to be dealt as an int32.
129    /// For instance :
130    /// - a 'Little Endian' image, read with a little endian processor
131    /// will have a SwapCode= 1234 (the order is OK; nothing to do)
132    /// - a 'Little Endian' image, read with a big endian procesor
133    /// will have a SwapCode= 4321 (the order is wrong; int32 an int16 must be
134    /// swapped)
135    /// note : values 2143, 4321, 3412 remain for the ACR-NEMA time, and
136    /// the well known 'Bad Big Endian' and 'Bad Little Endian' codes
137    int SwapCode;
138
139    ///\brief whether we already parsed group 0002 (Meta Elements)
140    bool Group0002Parsed;
141
142    ///\brief whether file has a DCM Preamble
143    bool HasDCMPreamble;
144
145    /// File Pointer, opened during Document parsing.
146    std::ifstream *Fp;
147
148    /// ACR, ACR_LIBIDO, ExplicitVR, ImplicitVR, Unknown
149    FileType Filetype;  
150
151    /// After opening the file, we read HEADER_LENGTH_TO_READ bytes.
152    static const unsigned int HEADER_LENGTH_TO_READ; 
153    /// \brief Elements whose value is longer than MAX_SIZE_LOAD_ELEMENT_VALUE
154    /// are NOT loaded.
155    static const unsigned int MAX_SIZE_LOAD_ELEMENT_VALUE;
156
157    /// User supplied list of elements to Anonymize
158    ListElements UserAnonymizeList;
159
160    /// User supplied list of elements to force Load
161    ListElements UserForceLoadList;
162
163    /// \brief Bit string integer (each one considered as a boolean)
164    ///        Bit 0 : Skip Sequences,    if possible
165    ///        Bit 1 : Skip Shadow Groups if possible
166    ///        Probabely, some more to add
167    int LoadMode;
168    
169    /// \brief Whether the gdcm::Document is already parsed/loaded :
170    /// False from the creation of the gdcm::Document untill 
171    ///   gdcm::Document:Load()
172    bool IsDocumentAlreadyLoaded; // FIXME : probabely useless now
173
174    /// Whether the gdcm::Document was modified since the last Load()
175    bool IsDocumentModified;
176
177 private:
178 // Methods
179    void Initialize();
180    bool DoTheLoadingDocumentJob(); 
181      
182       // System access (meaning endian related !?)
183    uint16_t SwapShort(uint16_t);
184    uint32_t SwapLong(uint32_t);
185    double SwapDouble(double);
186    /// \brief  Unswaps back the bytes of 2-bytes long integer 
187    ///         so they agree with the processor order.
188    uint16_t UnswapShort(uint16_t a) { return SwapShort(a);}
189    /// \brief  Unswaps back the bytes of 4-byte long integer 
190    ///         so they agree with the processor order.
191    uint32_t UnswapLong(uint32_t a) { return SwapLong(a);}
192    
193    // Read
194    void ParseDES(DocEntrySet *set, long offset, long l_max, bool delim_mode);
195    void ParseSQ (SeqEntry *seq,    long offset, long l_max, bool delim_mode);
196
197    void LoadDocEntry         (DocEntry *e, bool forceLoad = false);
198    void FindDocEntryLength   (DocEntry *e) throw ( FormatError );
199    uint32_t FindDocEntryLengthOBOrOW() throw( FormatUnexpected );
200    VRKey FindDocEntryVR();
201    bool CheckDocEntryVR      (const VRKey &k);
202
203    void SkipDocEntry          (DocEntry *entry);
204    void SkipToNextDocEntry    (DocEntry *entry);
205
206    void FixDocEntryFoundLength(DocEntry *entry, uint32_t l);
207    bool IsDocEntryAnInteger   (DocEntry *entry);
208
209    bool CheckSwap();
210    void SwitchByteSwapCode();
211    void SetMaxSizeLoadEntry(long);
212
213    // DocEntry related utilities
214    DocEntry *ReadNextDocEntry();
215
216    void HandleBrokenEndian  (uint16_t &group, uint16_t &elem);
217    void HandleOutOfGroup0002(uint16_t &group, uint16_t &elem);
218    DocEntry *Backtrack(DocEntry *docEntry);
219
220 // Variables
221    /// Public dictionary used to parse this header
222    Dict *RefPubDict;
223    /// \brief Optional "shadow dictionary" (private elements) used to parse
224    /// this header
225    Dict *RefShaDict;
226
227    /// \brief Size threshold above which an element value will NOT be loaded
228    /// in memory (to avoid loading the image/volume itself). By default,
229    /// this upper bound is fixed to 1024 bytes (which might look reasonable
230    /// when one considers the definition of the various VR contents).
231    uint32_t MaxSizeLoadEntry;
232
233    /// \brief to allow any inner method to know current tag Group number 
234    uint16_t CurrentGroup;
235    /// \brief to allow any inner method to know current tag Element number 
236    uint16_t CurrentElem; 
237      
238 //  uint32_t GenerateFreeTagKeyInGroup(uint16_t group);
239 //  void BuildFlatHashTableRecurse( TagDocEntryHT &builtHT,
240 //                                  DocEntrySet *set );
241
242 };
243
244 } // end namespace gdcm
245
246 //-----------------------------------------------------------------------------
247 #endif