1 /*
2  *
3  *  Copyright (C) 2008-2012, OFFIS e.V. and ICSMED AG, Oldenburg, Germany
4  *  Copyright (C) 2013-2017, J. Riesmeier, Oldenburg, Germany
5  *  All rights reserved.  See COPYRIGHT file for details.
6  *
7  *  Header file for class DRTRealWorldValueMappingSequence
8  *
9  *  Generated automatically from DICOM PS 3.3-2017e
10  *  File created on 2017-12-05 09:30:54
11  *
12  */
13 
14 
15 #ifndef DRTRWVMS_H
16 #define DRTRWVMS_H
17 
18 #include "dcmtk/config/osconfig.h"     // make sure OS specific configuration is included first
19 
20 #include "dcmtk/ofstd/oflist.h"        // for standard list class
21 #include "dcmtk/dcmrt/drttypes.h"      // module-specific helper class
22 #include "dcmtk/dcmrt/seq/drtmucs.h"   // for MeasurementUnitsCodeSequence
23 #include "dcmtk/dcmrt/seq/drtqds.h"    // for QuantityDefinitionSequence
24 
25 
26 /** Interface class for RealWorldValueMappingSequence (0040,9096)
27  */
28 class DCMTK_DCMRT_EXPORT DRTRealWorldValueMappingSequence
29   : protected DRTTypes
30 {
31 
32   public:
33 
34     /** Item class
35      */
36     class DCMTK_DCMRT_EXPORT Item
37       : protected DRTTypes
38     {
39 
40       public:
41 
42       // --- constructors, destructor and operators ---
43 
44         /** (default) constructor
45          *  @param emptyDefaultItem flag used to mark the empty default item
46          */
47         Item(const OFBool emptyDefaultItem = OFFalse);
48 
49         /** copy constructor
50          *  @param copy item object to be copied
51          */
52         Item(const Item &copy);
53 
54         /** destructor
55          */
56         virtual ~Item();
57 
58         /** assigment operator
59          *  @param copy item object to be copied
60          *  @return reference to this object
61          */
62         Item &operator=(const Item &copy);
63 
64       // --- general methods ---
65 
66         /** clear all internal member variables
67          */
68         void clear();
69 
70         /** check if item is empty
71          *  @return OFTrue if item is empty, OFFalse otherwise
72          */
73         OFBool isEmpty();
74 
75         /** check if item is valid, i.e.\ not the empty default item
76          *  @return OFTrue if item is valid, OFFalse otherwise
77          */
78         OFBool isValid() const;
79 
80       // --- input/output methods ---
81 
82         /** read elements from sequence item
83          *  @param  item    reference to DICOM sequence item from which the elements should be read
84          *  @return status, EC_Normal if successful, an error code otherwise
85          */
86         OFCondition read(DcmItem &item);
87 
88         /** write elements to sequence item
89          *  @param  item    reference to DICOM sequence item to which the elements should be written
90          *  @return status, EC_Normal if successful, an error code otherwise
91          */
92         OFCondition write(DcmItem &item);
93 
94       // --- get DICOM attribute values ---
95 
96         /** get DoubleFloatRealWorldValueFirstValueMapped (0040,9214)
97          *  @param  value  reference to variable in which the value should be stored
98          *  @param  pos    index of the value to get (0..vm-1)
99          *  @return status, EC_Normal if successful, an error code otherwise
100          */
101         OFCondition getDoubleFloatRealWorldValueFirstValueMapped(Float64 &value, const unsigned long pos = 0) const;
102 
103         /** get DoubleFloatRealWorldValueLastValueMapped (0040,9213)
104          *  @param  value  reference to variable in which the value should be stored
105          *  @param  pos    index of the value to get (0..vm-1)
106          *  @return status, EC_Normal if successful, an error code otherwise
107          */
108         OFCondition getDoubleFloatRealWorldValueLastValueMapped(Float64 &value, const unsigned long pos = 0) const;
109 
110         /** get LUTExplanation (0028,3003)
111          *  @param  value  reference to variable in which the value should be stored
112          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
113          *  @return status, EC_Normal if successful, an error code otherwise
114          */
115         OFCondition getLUTExplanation(OFString &value, const signed long pos = 0) const;
116 
117         /** get LUTLabel (0040,9210)
118          *  @param  value  reference to variable in which the value should be stored
119          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
120          *  @return status, EC_Normal if successful, an error code otherwise
121          */
122         OFCondition getLUTLabel(OFString &value, const signed long pos = 0) const;
123 
124         /** get RealWorldValueFirstValueMapped (0040,9216)
125          *  @param  value  reference to variable in which the value should be stored
126          *  @param  pos    index of the value to get (0..vm-1)
127          *  @return status, EC_Normal if successful, an error code otherwise
128          */
129         OFCondition getRealWorldValueFirstValueMapped(Uint16 &value, const unsigned long pos = 0) const;
130 
131         /** get RealWorldValueIntercept (0040,9224)
132          *  @param  value  reference to variable in which the value should be stored
133          *  @param  pos    index of the value to get (0..vm-1)
134          *  @return status, EC_Normal if successful, an error code otherwise
135          */
136         OFCondition getRealWorldValueIntercept(Float64 &value, const unsigned long pos = 0) const;
137 
138         /** get RealWorldValueLUTData (0040,9212)
139          *  @param  value  reference to variable in which the value should be stored
140          *  @param  pos    index of the value to get (0..vm-1)
141          *  @return status, EC_Normal if successful, an error code otherwise
142          */
143         OFCondition getRealWorldValueLUTData(Float64 &value, const unsigned long pos = 0) const;
144 
145         /** get RealWorldValueLastValueMapped (0040,9211)
146          *  @param  value  reference to variable in which the value should be stored
147          *  @param  pos    index of the value to get (0..vm-1)
148          *  @return status, EC_Normal if successful, an error code otherwise
149          */
150         OFCondition getRealWorldValueLastValueMapped(Uint16 &value, const unsigned long pos = 0) const;
151 
152         /** get RealWorldValueSlope (0040,9225)
153          *  @param  value  reference to variable in which the value should be stored
154          *  @param  pos    index of the value to get (0..vm-1)
155          *  @return status, EC_Normal if successful, an error code otherwise
156          */
157         OFCondition getRealWorldValueSlope(Float64 &value, const unsigned long pos = 0) const;
158 
159       // --- get DICOM sequence attributes ---
160 
161         /** get MeasurementUnitsCodeSequence (0040,08ea)
162          *  @return reference to sequence element
163          */
getMeasurementUnitsCodeSequence()164         DRTMeasurementUnitsCodeSequence &getMeasurementUnitsCodeSequence()
165             { return MeasurementUnitsCodeSequence; }
166 
167         /** get MeasurementUnitsCodeSequence (0040,08ea)
168          *  @return const reference to sequence element
169          */
getMeasurementUnitsCodeSequence()170         const DRTMeasurementUnitsCodeSequence &getMeasurementUnitsCodeSequence() const
171             { return MeasurementUnitsCodeSequence; }
172 
173         /** get QuantityDefinitionSequence (0040,9220)
174          *  @return reference to sequence element
175          */
getQuantityDefinitionSequence()176         DRTQuantityDefinitionSequence &getQuantityDefinitionSequence()
177             { return QuantityDefinitionSequence; }
178 
179         /** get QuantityDefinitionSequence (0040,9220)
180          *  @return const reference to sequence element
181          */
getQuantityDefinitionSequence()182         const DRTQuantityDefinitionSequence &getQuantityDefinitionSequence() const
183             { return QuantityDefinitionSequence; }
184 
185       // --- set DICOM attribute values ---
186 
187         /** set DoubleFloatRealWorldValueFirstValueMapped (0040,9214)
188          *  @param  value  value to be set (should be valid for this VR)
189          *  @param  pos    index of the value to be set (0..vm-1), vm=1
190          *  @return status, EC_Normal if successful, an error code otherwise
191          */
192         OFCondition setDoubleFloatRealWorldValueFirstValueMapped(const Float64 value, const unsigned long pos = 0);
193 
194         /** set DoubleFloatRealWorldValueLastValueMapped (0040,9213)
195          *  @param  value  value to be set (should be valid for this VR)
196          *  @param  pos    index of the value to be set (0..vm-1), vm=1
197          *  @return status, EC_Normal if successful, an error code otherwise
198          */
199         OFCondition setDoubleFloatRealWorldValueLastValueMapped(const Float64 value, const unsigned long pos = 0);
200 
201         /** set LUTExplanation (0028,3003)
202          *  @param  value  value to be set (single value only) or "" for no value
203          *  @param  check  check 'value' for conformance with VR (LO) and VM (1) if enabled
204          *  @return status, EC_Normal if successful, an error code otherwise
205          */
206         OFCondition setLUTExplanation(const OFString &value, const OFBool check = OFTrue);
207 
208         /** set LUTLabel (0040,9210)
209          *  @param  value  value to be set (single value only) or "" for no value
210          *  @param  check  check 'value' for conformance with VR (SH) and VM (1) if enabled
211          *  @return status, EC_Normal if successful, an error code otherwise
212          */
213         OFCondition setLUTLabel(const OFString &value, const OFBool check = OFTrue);
214 
215         /** set RealWorldValueFirstValueMapped (0040,9216)
216          *  @param  value  value to be set (should be valid for this VR)
217          *  @param  pos    index of the value to be set (0..vm-1), vm=1
218          *  @return status, EC_Normal if successful, an error code otherwise
219          */
220         OFCondition setRealWorldValueFirstValueMapped(const Uint16 value, const unsigned long pos = 0);
221 
222         /** set RealWorldValueIntercept (0040,9224)
223          *  @param  value  value to be set (should be valid for this VR)
224          *  @param  pos    index of the value to be set (0..vm-1), vm=1
225          *  @return status, EC_Normal if successful, an error code otherwise
226          */
227         OFCondition setRealWorldValueIntercept(const Float64 value, const unsigned long pos = 0);
228 
229         /** set RealWorldValueLUTData (0040,9212)
230          *  @param  value  value to be set (should be valid for this VR)
231          *  @param  pos    index of the value to be set (0..vm-1), vm=1-n
232          *  @return status, EC_Normal if successful, an error code otherwise
233          */
234         OFCondition setRealWorldValueLUTData(const Float64 value, const unsigned long pos = 0);
235 
236         /** set RealWorldValueLastValueMapped (0040,9211)
237          *  @param  value  value to be set (should be valid for this VR)
238          *  @param  pos    index of the value to be set (0..vm-1), vm=1
239          *  @return status, EC_Normal if successful, an error code otherwise
240          */
241         OFCondition setRealWorldValueLastValueMapped(const Uint16 value, const unsigned long pos = 0);
242 
243         /** set RealWorldValueSlope (0040,9225)
244          *  @param  value  value to be set (should be valid for this VR)
245          *  @param  pos    index of the value to be set (0..vm-1), vm=1
246          *  @return status, EC_Normal if successful, an error code otherwise
247          */
248         OFCondition setRealWorldValueSlope(const Float64 value, const unsigned long pos = 0);
249 
250       private:
251 
252         /// internal flag used to mark the empty default item
253         /*const*/ OFBool EmptyDefaultItem;
254 
255         /// DoubleFloatRealWorldValueFirstValueMapped (0040,9214) vr=FD, vm=1, type=1C
256         DcmFloatingPointDouble DoubleFloatRealWorldValueFirstValueMapped;
257         /// DoubleFloatRealWorldValueLastValueMapped (0040,9213) vr=FD, vm=1, type=1C
258         DcmFloatingPointDouble DoubleFloatRealWorldValueLastValueMapped;
259         /// LUTExplanation (0028,3003) vr=LO, vm=1, type=1
260         DcmLongString LUTExplanation;
261         /// LUTLabel (0040,9210) vr=SH, vm=1, type=1
262         DcmShortString LUTLabel;
263         /// MeasurementUnitsCodeSequence (0040,08ea) vr=SQ, vm=1, type=1
264         DRTMeasurementUnitsCodeSequence MeasurementUnitsCodeSequence;
265         /// QuantityDefinitionSequence (0040,9220) vr=SQ, vm=1, type=3
266         DRTQuantityDefinitionSequence QuantityDefinitionSequence;
267         /// RealWorldValueFirstValueMapped (0040,9216) vr=US/SS, vm=1, type=1C
268         DcmUnsignedShort RealWorldValueFirstValueMapped;
269         /// RealWorldValueIntercept (0040,9224) vr=FD, vm=1, type=1C
270         DcmFloatingPointDouble RealWorldValueIntercept;
271         /// RealWorldValueLUTData (0040,9212) vr=FD, vm=1-n, type=1C
272         DcmFloatingPointDouble RealWorldValueLUTData;
273         /// RealWorldValueLastValueMapped (0040,9211) vr=US/SS, vm=1, type=1C
274         DcmUnsignedShort RealWorldValueLastValueMapped;
275         /// RealWorldValueSlope (0040,9225) vr=FD, vm=1, type=1C
276         DcmFloatingPointDouble RealWorldValueSlope;
277 
278     };
279 
280   // --- constructors, destructor and operators ---
281 
282     /** (default) constructor
283      *  @param emptyDefaultSequence internal flag used to mark the empty default sequence
284      */
285     DRTRealWorldValueMappingSequence(const OFBool emptyDefaultSequence = OFFalse);
286 
287     /** copy constructor
288      *  @param copy sequence object to be copied
289      */
290     DRTRealWorldValueMappingSequence(const DRTRealWorldValueMappingSequence &copy);
291 
292     /** destructor
293      */
294     virtual ~DRTRealWorldValueMappingSequence();
295 
296     /** assigment operator
297      *  @param copy sequence object to be copied
298      *  @return reference to this object
299      */
300     DRTRealWorldValueMappingSequence &operator=(const DRTRealWorldValueMappingSequence &copy);
301 
302   // --- general methods ---
303 
304     /** clear all internal member variables
305      */
306     void clear();
307 
308     /** check if sequence is empty
309      *  @return OFTrue if sequence is empty, OFFalse otherwise
310      */
311     OFBool isEmpty();
312 
313     /** check if sequence is valid, i.e.\ not the empty default sequence
314      *  @return OFTrue if sequence is valid, OFFalse otherwise
315      */
316     OFBool isValid() const;
317 
318     /** get number of items in the sequence
319      *  @return number of items
320      */
321     size_t getNumberOfItems() const;
322 
323     /** goto first item in the sequence
324      *  @return status, EC_Normal if successful, an error code otherwise
325      */
326     OFCondition gotoFirstItem();
327 
328     /** goto next item in the sequence
329      *  @return status, EC_Normal if successful, an error code otherwise
330      */
331     OFCondition gotoNextItem();
332 
333     /** goto particular item in the sequence
334      *  @param  num  number of the item to be selected (0..num-1)
335      *  @return status, EC_Normal if successful, an error code otherwise
336      */
337     OFCondition gotoItem(const size_t num);
338 
339     /** get current item in the sequence
340      *  @param  item  reference to item pointer (result variable)
341      *  @return status, EC_Normal if successful, an error code otherwise
342      */
343     OFCondition getCurrentItem(Item *&item) const;
344 
345     /** get current item in the sequence
346      *  @return reference to specified item if successful, empty default item otherwise
347      */
348     Item &getCurrentItem();
349 
350     /** get current item in the sequence
351      *  @return const reference to specified item if successful, empty default item otherwise
352      */
353     const Item &getCurrentItem() const;
354 
355     /** get particular item in the sequence
356      *  @param  num   number of the item to be retrieved (0..num-1)
357      *  @param  item  reference to item pointer (result variable)
358      *  @return status, EC_Normal if successful, an error code otherwise
359      */
360     OFCondition getItem(const size_t num, Item *&item);
361 
362     /** get particular item in the sequence
363      *  @param  num  number of the item to be retrieved (0..num-1)
364      *  @return reference to specified item if successful, empty default item otherwise
365      */
366     Item &getItem(const size_t num);
367 
368     /** get particular item in the sequence
369      *  @param  num  number of the item to be retrieved (0..num-1)
370      *  @return const reference to specified item if successful, empty default item otherwise
371      */
372     const Item &getItem(const size_t num) const;
373 
374     /** get particular item in the sequence
375      *  @param  num  number of the item to be retrieved (0..num-1)
376      *  @return reference to specified item if successful, empty default item otherwise
377      */
378     Item &operator[](const size_t num);
379 
380     /** get particular item in the sequence
381      *  @param  num  number of the item to be retrieved (0..num-1)
382      *  @return const reference to specified item if successful, empty default item otherwise
383      */
384     const Item &operator[](const size_t num) const;
385 
386     /** add new item to the end of this sequence
387      *  @param  item  reference to new item pointer (result variable)
388      *  @return status, EC_Normal if successful, an error code otherwise
389      */
390     OFCondition addItem(Item *&item);
391 
392     /** insert new item into the sequence
393      *  @param  pos   position where the new item is to be inserted (0..num)
394      *  @param  item  reference to new item pointer (result variable)
395      *  @return status, EC_Normal if successful, an error code otherwise
396      */
397     OFCondition insertItem(const size_t pos, Item *&item);
398 
399     /** remove particular item from the sequence
400      *  @param  pos  position of the item to be removed (0..num-1)
401      *  @return status, EC_Normal if successful, an error code otherwise
402      */
403     OFCondition removeItem(const size_t pos);
404 
405   // --- input/output methods ---
406 
407     /** read sequence of items from dataset
408      *  @param  dataset     reference to DICOM dataset from which the sequence should be read
409      *  @param  card        cardinality (valid range for number of items)
410      *  @param  type        value type (valid value: "1", "1C", "2" or something else which is not checked)
411      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
412      *  @return status, EC_Normal if successful, an error code otherwise
413      */
414     OFCondition read(DcmItem &dataset,
415                      const OFString &card,
416                      const OFString &type,
417                      const char *moduleName = NULL);
418 
419     /** write sequence of items to dataset
420      *  @param  dataset     reference to DICOM dataset to which the sequence should be written
421      *  @param  card        cardinality (valid range for number of items)
422      *  @param  type        value type (valid value: "1", "2" or something else which is not checked)
423      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
424      *  @return status, EC_Normal if successful, an error code otherwise
425      */
426     OFCondition write(DcmItem &dataset,
427                       const OFString &card,
428                       const OFString &type,
429                       const char *moduleName = NULL);
430 
431   protected:
432 
433     /** goto particular item in the sequence
434      *  @param  num       number of the item to be selected (0..num-1)
435      *  @param  iterator  list iterator storing the position of the item
436      *  @return status, EC_Normal if successful, an error code otherwise
437      */
438     OFCondition gotoItem(const size_t num,
439                          OFListIterator(Item *) &iterator);
440 
441     /** goto particular item in the sequence
442      *  @param  num       number of the item to be selected (0..num-1)
443      *  @param  iterator  list iterator storing the position of the item
444      *  @return status, EC_Normal if successful, an error code otherwise
445      */
446     OFCondition gotoItem(const size_t num,
447                          OFListConstIterator(Item *) &iterator) const;
448 
449   private:
450 
451     /// internal flag used to mark the empty default sequence
452     /*const*/ OFBool EmptyDefaultSequence;
453 
454     /// list of items in this sequence
455     OFList<Item *>         SequenceOfItems;
456     /// currently selected item
457     OFListIterator(Item *) CurrentItem;
458     /// empty default item
459     Item                   EmptyItem;
460 
461 };
462 
463 
464 #endif
465