1 /*
2  *
3  *  Copyright (C) 2016-2019, Open Connections GmbH
4  *  All rights reserved.  See COPYRIGHT file for details.
5  *
6  *  This software and supporting documentation are maintained by
7  *
8  *    OFFIS e.V.
9  *    R&D Division Health
10  *    Escherweg 2
11  *    D-26121 Oldenburg, Germany
12  *
13  *
14  *  Module:  dcmtract
15  *
16  *  Author:  Michael Onken
17  *
18  *  Purpose: Statistics from a Tractography Results IOD
19  *
20  */
21 
22 
23 #ifndef TRCSTATISTIC_H
24 #define TRCSTATISTIC_H
25 
26 #include "dcmtk/config/osconfig.h"
27 #include "dcmtk/dcmiod/modbase.h"
28 #include "dcmtk/dcmiod/iodutil.h"
29 #include "dcmtk/dcmiod/iodmacro.h"
30 #include "dcmtk/dcmtract/trctypes.h"
31 
32 // Forward declarations
33 
34 class CodeSequenceMacro;
35 
36 /** Base class representing a statistic within the "Tractography Results" IOD. A
37  *  statistic is of a certain type and applies to a specific region of interest.
38  *  For each Track Set and for each track there may be one or more statistics
39  *  defined. The specializations can be found in classes TrcTracksStatistic and
40  *  TrcTrackSetStatistic.
41  */
42 class DCMTK_DCMTRACT_EXPORT TrcStatistic
43 : public IODComponent
44 {
45 
46 public:
47 
48   /// Allow read/write functions in DcmIODUtil to access class internals
49   friend class DcmIODUtil;
50 
51   /** Constructor
52    */
53   TrcStatistic();
54 
55   /** Destructor, frees memory
56    */
57   virtual ~TrcStatistic();
58 
59   /** Clears all data
60    */
61   virtual void clearData();
62 
63   /** Read attributes from given item into this class
64    *  @param source  The source to read from
65    *  @param clearOldData If OFTrue, old data is cleared before reading. Otherwise
66    *         old data is overwritten (or amended)
67    *  @result EC_Normal if reading was successful, error otherwise
68    */
69   virtual OFCondition read(DcmItem& source,
70                            const OFBool clearOldData = OFTrue);
71 
72   /** Write attributes from this class into given item
73    *  @param  destination The item to write to
74    *  @result EC_Normal if writing was successful, error otherwise
75    */
76   virtual OFCondition write(DcmItem& destination);
77 
78   /** Get descriptive information of statistic
79    *  @param  typeCode Returns type of statistic
80    *  @param  typeModifierCode Returns region of interest
81    *  @param  unitsCode Returns physical units of the statistic value
82    *  @return EC_Normal if getting was successful, error otherwise.
83    */
84   virtual OFCondition get(CodeSequenceMacro& typeCode,
85                           CodeSequenceMacro& typeModifierCode,
86                           CodeSequenceMacro& unitsCode);
87 
88   /** Resets rules to their original values
89    */
90   virtual void resetRules();
91 
92 protected:
93 
94   /** Set descriptive information of statistic
95    *  @param  typeCode The type of statistic, DICOM prescribes codes from
96    *          CID 7263 "Diffusion Tractography Measurement Types"
97    *  @param  typeModifierCode Defines the region of interest, DICOM prescribes
98    *          code from CID 7464 "General Region of Interest Measurement
99    *          Modifiers"
100    *  @param  unitsCode The physical units of the statistic value, DICOM
101    *          prescribes code from CID 82 "Units of Measurement" (UCUM).
102    *  @return EC_Normal if setting was successful, error otherwise.
103    */
104   virtual OFCondition setCommon(const CodeSequenceMacro& typeCode,
105                                 const CodeSequenceMacro& typeModifierCode,
106                                 const CodeSequenceMacro& unitsCode);
107 
108   /// Single item from Concept Name Code Sequence
109   CodeSequenceMacro m_Type;
110 
111   /// Single item from Modifier Code Sequence
112   CodeSequenceMacro m_TypeModifier;
113 
114   /// Single item from Unit Code Sequence
115   CodeSequenceMacro m_Units;
116 
117   /// Floating Point Value(s), one for each Track in Track Set (for Track
118   /// Statistic), or a single value in case of Track Set Statistic
119   OFVector<Float32*> m_Values;
120 };
121 
122 
123 /** Class representing a statistic for Tracks in Track Set. Besides describing
124  *  information like type of statistic, region o interest and units of the
125  *  statistic values, the statistic defines a single statistic value for each
126  *  track. Thus the number of statistic values must be identical to the number
127  *  of tracks in the containing Track Set.
128  */
129 class TrcTracksStatistic : public TrcStatistic
130 {
131 public:
132 
133   /** Constructor
134    */
135   TrcTracksStatistic();
136 
137   /** Destructor, frees memory
138    */
139   ~TrcTracksStatistic();
140 
141   /** Create track statistic by providing the required information
142    *  @param  typeCode The value for which the statistic is a summary. DICOM
143    *          prescribes code from CID 7263 "Diffusion Tractography Measurement
144    *          Types"
145    *  @param  typeModifierCode The region of interest of the statistic. DICOM
146    *          prescribes code from CID 7464 "General Region of Interest
147    *          Measurement Modifiers"
148    *  @param  unitsCode The physical units of the statistic value. DICOM
149    *          prescribes code from CID 82 "Units of Measurement".
150    *  @param  statisticValues The statistic values
151    *  @param  numValues The number of statistic values in statisticValues, must
152    *          be equal to number of Tracks in the Track Set that this statistic
153    *          applies to
154    *  @param  statistic Returns the resulting TrcTracksStatistic object (NULL
155    *          in case of any error)
156    *  @return EC_Normal if creation was successful, error otherwise
157    */
158   static OFCondition create(const CodeSequenceMacro& typeCode,
159                             const CodeSequenceMacro& typeModifierCode,
160                             const CodeSequenceMacro& unitsCode,
161                             const Float32* statisticValues,
162                             const size_t numValues,
163                             TrcTracksStatistic*& statistic /* result */);
164 
165   /** Read attributes from given item into this class
166    *  @param source  The source to read from
167    *  @param clearOldData If OFTrue, old data is cleared before reading. Otherwise
168    *         old data is overwritten (or amended)
169    *  @result EC_Normal if reading was successful, error otherwise
170    */
171   virtual OFCondition read(DcmItem& source,
172                            const OFBool clearOldData = OFTrue);
173 
174   /** Write attributes from this class into given item
175    *  @param  destination The item to write to
176    *  @result EC_Normal if writing was successful, error otherwise
177    */
178   virtual OFCondition write(DcmItem& destination);
179 
180   /** Resets rules to their original values
181    */
182   virtual void resetRules();
183 
184   /** Get name of component
185    *  @return Name of the module ("TrackStatisticsSequenceItem")
186    */
187   virtual OFString getName() const;
188 
189   /** Set Track statistic
190    *  @param  typeCode The value for which the statistic is a summary. DICOM
191    *          prescribes code from CID 7263 "Diffusion Tractography Measurement
192    *          Types"
193    *  @param  typeModifierCode The region of interest of the statistic. DICOM
194    *          prescribes code from CID 7464 "General Region of Interest
195    *          Measurement Modifiers"
196    *  @param  unitsCode The physical units of the statistic value. DICOM
197    *          prescribes code from CID 82 "Units of Measurement".
198    *  @param  statisticValues The statistic values
199    *  @param  numValues The number of statistic values in statisticValues, must
200    *          equal the number of tracks in containing Track Set
201    *  @return EC_Normal if setting was successful, error otherwise
202    */
203   virtual OFCondition set(const CodeSequenceMacro& typeCode,
204                           const CodeSequenceMacro& typeModifierCode,
205                           const CodeSequenceMacro& unitsCode,
206                           const Float32* statisticValues,
207                           const size_t numValues);
208 
209   /** Get Track statistic information
210    *  @param  typeCode Returns value for which the statistic is a summary.
211    *  @param  typeModifierCode Returns region of interest of the statistic.
212    *  @param  unitsCode Returns physical units of the statistic value.
213    *  @param  statisticValues Returns statistic values
214    *  @param  numValues Returns number of statistic values in statisticValues,
215    *          should be equal to number of tracks in containing Track Set
216    *  @return EC_Normal if data could be retrieved, error otherwise
217    */
218   virtual OFCondition get(CodeSequenceMacro& typeCode,
219                           CodeSequenceMacro& typeModifierCode,
220                           CodeSequenceMacro& unitsCode,
221                           const Float32*& statisticValues,
222                           unsigned long& numValues);
223 
224   // Make sure the original virtual get() function from TrcStatistic
225   // stays visible
226   using TrcStatistic::get;
227 };
228 
229 /** Class representing a Track Set statistic, i.e. a single statistic value that
230  *  is amended by information about type of statistic, region of interest it as
231  *  well as physical unit of the value. A Track Set can define 0 or more
232  *  statistics.
233  */
234 class TrcTrackSetStatistic : public TrcStatistic
235 {
236 public:
237 
238   /** Constructor
239    */
240   TrcTrackSetStatistic();
241 
242   /** Destructor, frees memory
243    */
244   virtual ~TrcTrackSetStatistic();
245 
246   /** Create track statistic by providing the required information
247    *  @param  typeCode The value for which the statistic is a summary. DICOM
248    *          prescribes code from CID 7263 "Diffusion Tractography Measurement
249    *          Types"
250    *  @param  typeModifierCode The region of interest of the statistic. DICOM
251    *          prescribes code from CID 7464 "General Region of Interest
252    *          Measurement Modifiers"
253    *  @param  unitsCode The physical units of the statistic value. DICOM
254    *          prescribes code from CID 82 "Units of Measurement".
255    *  @param  statisticValue The statistic value
256    *  @param  statistic Returns the resulting TrcTrackSetStatistic object (NULL
257    *          in case of any error)
258    *  @return EC_Normal if creation was successful, error otherwise
259    */
260   static OFCondition create(const CodeSequenceMacro& typeCode,
261                             const CodeSequenceMacro& typeModifierCode,
262                             const CodeSequenceMacro& unitsCode,
263                             const Float64 statisticValue,
264                             TrcTrackSetStatistic*& statistic /* result */);
265 
266   /** Read attributes from given item into this class
267    *  @param source  The source to read from
268    *  @param clearOldData If OFTrue, old data is cleared before reading. Otherwise
269    *         old data is overwritten (or amended)
270    *  @result EC_Normal if reading was successful, error otherwise
271    */
272   virtual OFCondition read(DcmItem& source,
273                            const OFBool clearOldData = OFTrue);
274 
275   /** Write attributes from this class into given item
276    *  @param  destination The item to write to
277    *  @result EC_Normal if writing was successful, error otherwise
278    */
279   virtual OFCondition write(DcmItem& destination);
280 
281   /** Resets rules to their original values
282    */
283   virtual void resetRules();
284 
285   /** Get name of component
286    *  @return Name of the module ("TrackSetStatisticsSequenceItem")
287    */
288   virtual OFString getName() const;
289 
290   /** Set Track Set statistic
291    *  @param  typeCode The value for which the statistic is a summary. DICOM
292    *          prescribes code from CID 7263 "Diffusion Tractography Measurement
293    *          Types"
294    *  @param  typeModifierCode The region of interest of the statistic. DICOM
295    *          prescribes code from CID 7464 "General Region of Interest
296    *          Measurement Modifiers"
297    *  @param  unitsCode The physical units of the statistic value. DICOM
298    *          prescribes code from CID 82 "Units of Measurement".
299    *  @param  statisticValue The statistic value
300    *  @return EC_Normal if setting was successful, error otherwise
301    */
302   virtual OFCondition set(const CodeSequenceMacro& typeCode,
303                           const CodeSequenceMacro& typeModifierCode,
304                           const CodeSequenceMacro& unitsCode,
305                           const Float64 statisticValue);
306 
307   /** Get Track Set statistic information
308    *  @param  typeCode Returns value for which the statistic is a summary.
309    *  @param  typeModifierCode Returns region of interest of the statistic.
310    *  @param  unitsCode Returns physical units of the statistic value.
311    *  @param  statisticValue Returns the statistic value
312    *  @return EC_Normal if data could be retrieved, error otherwise
313    */
314   virtual OFCondition get(CodeSequenceMacro& typeCode,
315                           CodeSequenceMacro& typeModifierCode,
316                           CodeSequenceMacro& unitsCode,
317                           Float64& statisticValue);
318 
319     // Make sure the original virtual get() function from TrcStatistic
320   // stays visible
321   using TrcStatistic::get;
322 
323 };
324 
325 
326 #endif // TRCSTATISTIC_H
327