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 DRTROIContourSequence
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 DRTRCS_H
16 #define DRTRCS_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/drtcs.h"     // for ContourSequence
23 
24 
25 /** Interface class for ROIContourSequence (3006,0039)
26  */
27 class DCMTK_DCMRT_EXPORT DRTROIContourSequence
28   : protected DRTTypes
29 {
30 
31   public:
32 
33     /** Item class
34      */
35     class DCMTK_DCMRT_EXPORT Item
36       : protected DRTTypes
37     {
38 
39       public:
40 
41       // --- constructors, destructor and operators ---
42 
43         /** (default) constructor
44          *  @param emptyDefaultItem flag used to mark the empty default item
45          */
46         Item(const OFBool emptyDefaultItem = OFFalse);
47 
48         /** copy constructor
49          *  @param copy item object to be copied
50          */
51         Item(const Item &copy);
52 
53         /** destructor
54          */
55         virtual ~Item();
56 
57         /** assigment operator
58          *  @param copy item object to be copied
59          *  @return reference to this object
60          */
61         Item &operator=(const Item &copy);
62 
63       // --- general methods ---
64 
65         /** clear all internal member variables
66          */
67         void clear();
68 
69         /** check if item is empty
70          *  @return OFTrue if item is empty, OFFalse otherwise
71          */
72         OFBool isEmpty();
73 
74         /** check if item is valid, i.e.\ not the empty default item
75          *  @return OFTrue if item is valid, OFFalse otherwise
76          */
77         OFBool isValid() const;
78 
79       // --- input/output methods ---
80 
81         /** read elements from sequence item
82          *  @param  item    reference to DICOM sequence item from which the elements should be read
83          *  @return status, EC_Normal if successful, an error code otherwise
84          */
85         OFCondition read(DcmItem &item);
86 
87         /** write elements to sequence item
88          *  @param  item    reference to DICOM sequence item to which the elements should be written
89          *  @return status, EC_Normal if successful, an error code otherwise
90          */
91         OFCondition write(DcmItem &item);
92 
93       // --- get DICOM attribute values ---
94 
95         /** get ROIDisplayColor (3006,002a)
96          *  @param  value  reference to variable in which the value should be stored
97          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
98          *  @return status, EC_Normal if successful, an error code otherwise
99          */
100         OFCondition getROIDisplayColor(OFString &value, const signed long pos = 0) const;
101 
102         /** get ROIDisplayColor (3006,002a)
103          *  @param  value  reference to variable in which the value should be stored
104          *  @param  pos    index of the value to get (0..vm-1)
105          *  @return status, EC_Normal if successful, an error code otherwise
106          */
107         OFCondition getROIDisplayColor(Sint32 &value, const unsigned long pos = 0) const;
108 
109         /** get RecommendedDisplayCIELabValue (0062,000d)
110          *  @param  value  reference to variable in which the value should be stored
111          *  @param  pos    index of the value to get (0..vm-1)
112          *  @return status, EC_Normal if successful, an error code otherwise
113          */
114         OFCondition getRecommendedDisplayCIELabValue(Uint16 &value, const unsigned long pos = 0) const;
115 
116         /** get RecommendedDisplayGrayscaleValue (0062,000c)
117          *  @param  value  reference to variable in which the value should be stored
118          *  @param  pos    index of the value to get (0..vm-1)
119          *  @return status, EC_Normal if successful, an error code otherwise
120          */
121         OFCondition getRecommendedDisplayGrayscaleValue(Uint16 &value, const unsigned long pos = 0) const;
122 
123         /** get ReferencedROINumber (3006,0084)
124          *  @param  value  reference to variable in which the value should be stored
125          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
126          *  @return status, EC_Normal if successful, an error code otherwise
127          */
128         OFCondition getReferencedROINumber(OFString &value, const signed long pos = 0) const;
129 
130         /** get ReferencedROINumber (3006,0084)
131          *  @param  value  reference to variable in which the value should be stored
132          *  @param  pos    index of the value to get (0..vm-1)
133          *  @return status, EC_Normal if successful, an error code otherwise
134          */
135         OFCondition getReferencedROINumber(Sint32 &value, const unsigned long pos = 0) const;
136 
137       // --- get DICOM sequence attributes ---
138 
139         /** get ContourSequence (3006,0040)
140          *  @return reference to sequence element
141          */
getContourSequence()142         DRTContourSequence &getContourSequence()
143             { return ContourSequence; }
144 
145         /** get ContourSequence (3006,0040)
146          *  @return const reference to sequence element
147          */
getContourSequence()148         const DRTContourSequence &getContourSequence() const
149             { return ContourSequence; }
150 
151       // --- set DICOM attribute values ---
152 
153         /** set ROIDisplayColor (3006,002a)
154          *  @param  value  value to be set (possibly multi-valued) or "" for no value
155          *  @param  check  check 'value' for conformance with VR (IS) and VM (3) if enabled
156          *  @return status, EC_Normal if successful, an error code otherwise
157          */
158         OFCondition setROIDisplayColor(const OFString &value, const OFBool check = OFTrue);
159 
160         /** set RecommendedDisplayCIELabValue (0062,000d)
161          *  @param  value  value to be set (should be valid for this VR)
162          *  @param  pos    index of the value to be set (0..vm-1), vm=3
163          *  @return status, EC_Normal if successful, an error code otherwise
164          */
165         OFCondition setRecommendedDisplayCIELabValue(const Uint16 value, const unsigned long pos = 0);
166 
167         /** set RecommendedDisplayGrayscaleValue (0062,000c)
168          *  @param  value  value to be set (should be valid for this VR)
169          *  @param  pos    index of the value to be set (0..vm-1), vm=1
170          *  @return status, EC_Normal if successful, an error code otherwise
171          */
172         OFCondition setRecommendedDisplayGrayscaleValue(const Uint16 value, const unsigned long pos = 0);
173 
174         /** set ReferencedROINumber (3006,0084)
175          *  @param  value  value to be set (single value only) or "" for no value
176          *  @param  check  check 'value' for conformance with VR (IS) and VM (1) if enabled
177          *  @return status, EC_Normal if successful, an error code otherwise
178          */
179         OFCondition setReferencedROINumber(const OFString &value, const OFBool check = OFTrue);
180 
181       private:
182 
183         /// internal flag used to mark the empty default item
184         /*const*/ OFBool EmptyDefaultItem;
185 
186         /// ContourSequence (3006,0040) vr=SQ, vm=1, type=3
187         DRTContourSequence ContourSequence;
188         /// ROIDisplayColor (3006,002a) vr=IS, vm=3, type=3
189         DcmIntegerString ROIDisplayColor;
190         /// RecommendedDisplayCIELabValue (0062,000d) vr=US, vm=3, type=3
191         DcmUnsignedShort RecommendedDisplayCIELabValue;
192         /// RecommendedDisplayGrayscaleValue (0062,000c) vr=US, vm=1, type=3
193         DcmUnsignedShort RecommendedDisplayGrayscaleValue;
194         /// ReferencedROINumber (3006,0084) vr=IS, vm=1, type=1
195         DcmIntegerString ReferencedROINumber;
196 
197     };
198 
199   // --- constructors, destructor and operators ---
200 
201     /** (default) constructor
202      *  @param emptyDefaultSequence internal flag used to mark the empty default sequence
203      */
204     DRTROIContourSequence(const OFBool emptyDefaultSequence = OFFalse);
205 
206     /** copy constructor
207      *  @param copy sequence object to be copied
208      */
209     DRTROIContourSequence(const DRTROIContourSequence &copy);
210 
211     /** destructor
212      */
213     virtual ~DRTROIContourSequence();
214 
215     /** assigment operator
216      *  @param copy sequence object to be copied
217      *  @return reference to this object
218      */
219     DRTROIContourSequence &operator=(const DRTROIContourSequence &copy);
220 
221   // --- general methods ---
222 
223     /** clear all internal member variables
224      */
225     void clear();
226 
227     /** check if sequence is empty
228      *  @return OFTrue if sequence is empty, OFFalse otherwise
229      */
230     OFBool isEmpty();
231 
232     /** check if sequence is valid, i.e.\ not the empty default sequence
233      *  @return OFTrue if sequence is valid, OFFalse otherwise
234      */
235     OFBool isValid() const;
236 
237     /** get number of items in the sequence
238      *  @return number of items
239      */
240     size_t getNumberOfItems() const;
241 
242     /** goto first item in the sequence
243      *  @return status, EC_Normal if successful, an error code otherwise
244      */
245     OFCondition gotoFirstItem();
246 
247     /** goto next item in the sequence
248      *  @return status, EC_Normal if successful, an error code otherwise
249      */
250     OFCondition gotoNextItem();
251 
252     /** goto particular item in the sequence
253      *  @param  num  number of the item to be selected (0..num-1)
254      *  @return status, EC_Normal if successful, an error code otherwise
255      */
256     OFCondition gotoItem(const size_t num);
257 
258     /** get current item in the sequence
259      *  @param  item  reference to item pointer (result variable)
260      *  @return status, EC_Normal if successful, an error code otherwise
261      */
262     OFCondition getCurrentItem(Item *&item) const;
263 
264     /** get current item in the sequence
265      *  @return reference to specified item if successful, empty default item otherwise
266      */
267     Item &getCurrentItem();
268 
269     /** get current item in the sequence
270      *  @return const reference to specified item if successful, empty default item otherwise
271      */
272     const Item &getCurrentItem() const;
273 
274     /** get particular item in the sequence
275      *  @param  num   number of the item to be retrieved (0..num-1)
276      *  @param  item  reference to item pointer (result variable)
277      *  @return status, EC_Normal if successful, an error code otherwise
278      */
279     OFCondition getItem(const size_t num, Item *&item);
280 
281     /** get particular item in the sequence
282      *  @param  num  number of the item to be retrieved (0..num-1)
283      *  @return reference to specified item if successful, empty default item otherwise
284      */
285     Item &getItem(const size_t num);
286 
287     /** get particular item in the sequence
288      *  @param  num  number of the item to be retrieved (0..num-1)
289      *  @return const reference to specified item if successful, empty default item otherwise
290      */
291     const Item &getItem(const size_t num) const;
292 
293     /** get particular item in the sequence
294      *  @param  num  number of the item to be retrieved (0..num-1)
295      *  @return reference to specified item if successful, empty default item otherwise
296      */
297     Item &operator[](const size_t num);
298 
299     /** get particular item in the sequence
300      *  @param  num  number of the item to be retrieved (0..num-1)
301      *  @return const reference to specified item if successful, empty default item otherwise
302      */
303     const Item &operator[](const size_t num) const;
304 
305     /** add new item to the end of this sequence
306      *  @param  item  reference to new item pointer (result variable)
307      *  @return status, EC_Normal if successful, an error code otherwise
308      */
309     OFCondition addItem(Item *&item);
310 
311     /** insert new item into the sequence
312      *  @param  pos   position where the new item is to be inserted (0..num)
313      *  @param  item  reference to new item pointer (result variable)
314      *  @return status, EC_Normal if successful, an error code otherwise
315      */
316     OFCondition insertItem(const size_t pos, Item *&item);
317 
318     /** remove particular item from the sequence
319      *  @param  pos  position of the item to be removed (0..num-1)
320      *  @return status, EC_Normal if successful, an error code otherwise
321      */
322     OFCondition removeItem(const size_t pos);
323 
324   // --- input/output methods ---
325 
326     /** read sequence of items from dataset
327      *  @param  dataset     reference to DICOM dataset from which the sequence should be read
328      *  @param  card        cardinality (valid range for number of items)
329      *  @param  type        value type (valid value: "1", "1C", "2" or something else which is not checked)
330      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
331      *  @return status, EC_Normal if successful, an error code otherwise
332      */
333     OFCondition read(DcmItem &dataset,
334                      const OFString &card,
335                      const OFString &type,
336                      const char *moduleName = NULL);
337 
338     /** write sequence of items to dataset
339      *  @param  dataset     reference to DICOM dataset to which the sequence should be written
340      *  @param  card        cardinality (valid range for number of items)
341      *  @param  type        value type (valid value: "1", "2" or something else which is not checked)
342      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
343      *  @return status, EC_Normal if successful, an error code otherwise
344      */
345     OFCondition write(DcmItem &dataset,
346                       const OFString &card,
347                       const OFString &type,
348                       const char *moduleName = NULL);
349 
350   protected:
351 
352     /** goto particular item in the sequence
353      *  @param  num       number of the item to be selected (0..num-1)
354      *  @param  iterator  list iterator storing the position of the item
355      *  @return status, EC_Normal if successful, an error code otherwise
356      */
357     OFCondition gotoItem(const size_t num,
358                          OFListIterator(Item *) &iterator);
359 
360     /** goto particular item in the sequence
361      *  @param  num       number of the item to be selected (0..num-1)
362      *  @param  iterator  list iterator storing the position of the item
363      *  @return status, EC_Normal if successful, an error code otherwise
364      */
365     OFCondition gotoItem(const size_t num,
366                          OFListConstIterator(Item *) &iterator) const;
367 
368   private:
369 
370     /// internal flag used to mark the empty default sequence
371     /*const*/ OFBool EmptyDefaultSequence;
372 
373     /// list of items in this sequence
374     OFList<Item *>         SequenceOfItems;
375     /// currently selected item
376     OFListIterator(Item *) CurrentItem;
377     /// empty default item
378     Item                   EmptyItem;
379 
380 };
381 
382 
383 #endif
384