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