/* * * Copyright (C) 2016, Open Connections GmbH * All rights reserved. See COPYRIGHT file for details. * * This software and supporting documentation are maintained by * * OFFIS e.V. * R&D Division Health * Escherweg 2 * D-26121 Oldenburg, Germany * * * Module: dcmtract * * Author: Michael Onken * * Purpose: Class representing a Track Set from a Tractography Results IOD * */ #ifndef TRCTRACKSET_H #define TRCTRACKSET_H #include "dcmtk/config/osconfig.h" #include "dcmtk/dcmiod/modbase.h" #include "dcmtk/dcmiod/iodutil.h" #include "dcmtk/dcmiod/iodmacro.h" // for CodeSequenceMacro and CodeWithModifiers #include "dcmtk/dcmtract/trctypes.h" // Forward declarations class TrcTracksStatistic; class TrcTrackSetStatistic; class TrcTrack; class TrcMeasurement; /** Class representing a Track Set within the Tractography Results IOD. A Track * Set is a set of tracks (really), and might define a measurements and * statistics which then must be populated for all tracks in the set. * */ class DCMTK_DCMTRACT_EXPORT TrcTrackSet : public IODComponent { public: // Allow read/write functions in DcmIODUtil to access class internals friend class DcmIODUtil; /** Create TrcTrackSet object by proving required data * @param trackSetLabel Label for the Track Set (256 chars max, VR=LO) * @param trackSetDescription Description for the Track Set (2^32-2 bytes * maximum, VR=UT) * @param trackSetAnatomy Code for the anatomy the Track Set covers. DICOM * proposes CID 7710 "Tractography Anatomic Sites" (Baseline) * @param trackSetDiffusionModelCode Code for diffusion model used for Track * Set. DICOM prescribes code from CID 7261 "Diffusion Model Value * Types" * @param trackSetAlgorithmIdentification Algorithm used in order to * create Track Set. DICOM prescribes code from CID 7262 "Diffusion * Tractography Algorithm Families". * @param trackSet Returns the created Track Set, if successfull (NULL * otherwise) * @return EC_Normal if creation was successful, error otherwise */ static OFCondition create(const OFString& trackSetLabel, const OFString& trackSetDescription, const CodeWithModifiers& trackSetAnatomy, const CodeSequenceMacro& trackSetDiffusionModelCode, const CodeSequenceMacro& trackSetAlgorithmIdentification, TrcTrackSet*& trackSet /* result */); /** Destructor, frees memory */ virtual ~TrcTrackSet(); /** Resets rules to their original values */ virtual void resetRules(); /** Set missing values by inventing "default values". Automatically * called during write() by IODComponent. */ virtual void inventMissing(); /** Get name of component * @return Name of the module ("TrackSetSequenceItem") */ virtual OFString getName() const; /** Clear all data */ virtual void clearData(); /** Read attributes from given item into this class * @param source The source to read from * @param clearOldData If OFTrue, old data is cleared before reading. Otherwise * old data is overwritten (or amended) * @result EC_Normal if reading was successful, error otherwise */ virtual OFCondition read(DcmItem& source, const OFBool clearOldData = OFTrue); /** Get Tracks of this Track Set * @return Reference to Tracks of this Track Set */ virtual const OFVector& getTracks(); /** Write attributes from this class into given item * @param destination The item to write to * @result EC_Normal if writing was successful, error otherwise */ virtual OFCondition write(DcmItem& destination); /** Get Track Set Number (should be 1-n) * @param value Reference to variable in which the value should be stored * @param pos Index of the value to get (0..vm-1) * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition getTrackSetNumber(Uint16 &value, const unsigned long pos = 0) const; /** Get Track Set Label * @param value Reference to variable in which the value should be stored * @param pos Index of the value to get (0..vm-1), -1 for all components * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition getTrackSetLabel(OFString &value, const signed long pos = 0) const; /** Get Track Set Description * @param value Reference to variable in which the value should be stored * @param pos Index of the value to get (0..vm-1), -1 for all components * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition getTrackSetDescription(OFString &value, const signed long pos = 0) const; /** Get reference to Track Set Anatomical Type Code * @return Reference to the code */ virtual CodeWithModifiers& getTrackSetAnatomy(); /** Get copy of Recommended Display CIELab Value * @param L Returns CIELab L value * @param a Returns CIELab a value * @param b Returns CIELab b value * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition getRecommendedDisplayCIELabValue(Uint16& L, Uint16& a, Uint16& b); /** Get Recommended Line Thickness * @param value Reference to the variable in which the value should be stored * @param pos Index of the value to get (0..vm-1) * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition getRecommendedLineThickness(Float32& value, const unsigned long pos = 0); /** Get Laterality. * @param laterality Reference to the variable in which the value should be stored. * If value in dataset is not set at all, LAT_UNKNOWN is returned. If * a value is present that is not covered by the standard LAT_ERROR * is returned. * @return EC_Normal if successful (i.e. not LAT_ERROR), error code otherwise */ virtual OFCondition getLaterality(TrcTypes::E_TrackSetLaterality& laterality); /** Find measurements of a specific type. They can be retrieved afterwards by * using getMeasurement(). * @param type The measurement type to look for * @param measurementNumbers Returns the measurement indexes that are * of specified type. * @return Always returns EC_Normal (for now). */ virtual OFCondition findMeasurementsByType(const CodeSequenceMacro& type, OFVector& measurementNumbers); /** Get measurement by index. The index can be identified by using * findMeasurementsByType() or getMeasurementInfos() * @param measurementIndex The index of the measurement (starting from 0) * @param measurement Returns a reference to the measurement requested * @return Returns EC_Normal if measurement exists, TRC_EC_NoSuchMeasurement * otherwise */ virtual OFCondition getMeasurement(const size_t measurementIndex, const TrcMeasurement*& measurement); /** Get descriptive information of all measurements * @param typesAndUnits Returns vector of pairs, which each pair holding * a code for type of measurement and its physical units. */ virtual void getMeasurementInfos(OFVector >& typesAndUnits); /** Get access to all statistics defined for the Tracks in this Track Set * @return Returns reference to all Track statistics */ virtual const OFVector& getTrackStatistics(); /** Get access to all statistics defined for the Tracks in this Track Set * @return Returns reference to all Track statistics */ virtual const OFVector& getTrackSetStatistics(); /** Get access to diffusion acquisition code * @returns Returns reference to diffusion acquisition code */ virtual CodeSequenceMacro& getDiffusionAcquisitionCode(); /** Get access to diffusion model code used * @return Returns reference to diffusion model code */ virtual CodeSequenceMacro& getDiffusionModelCode(); /** Get access to tracking algorithm identification codes * @return Reference to tracking algorithm identification codes */ virtual OFVector& getTrackingAlgorithmIdentification(); /** Returns number of Tracks in Track Set * @return Number of Tracks in Track Set */ size_t getNumberOfTracks(); /** Returns number of Track Set Statistics in Track Set * @return Number of Track Set Statistics in Track Set */ size_t getNumberOfTrackSetStatistics(); /** Returns number of Track Statistics in Track Set * @return Number of Track Statistics in Track Set */ size_t getNumberOfTrackStatistics(); /** Returns number of Measurements in Track Set * @return Number of Measurements in Track Set */ size_t getNumberOfMeasurements(); /** Add track to Track Set * @param pointData Array of points (x,y,z coordinate for each point) * @param numPoints Number of points in pointData (i.e. number of point * coordinates divided by 3) * @param recommendedCIELabColors Recommended display color(s) as CIELab * values, i.e. L,a,b component(s). There are 3 modes: * 1) Single color: All points in track will be colored in that color * 2) No color (NULL): Color is not defined on a per-track basis but * must be defined on Track Set level * 3) One color per point: Colors for all points are provided * separately. * @param numColors Number of colors defined in recommendedCIELabColors * (must be either 0, 1 or numPoints) * @param result Returns the resulting Track if creation was successful, * error otherwise */ virtual OFCondition addTrack(const Float32* pointData, const size_t numPoints, const Uint16* recommendedCIELabColors, const size_t numColors, TrcTrack*& result); /** Add measurement for this Track Set * @param measurementCode The type of measurement. DICOM prescribes a code * from CID 7263 "Diffusion Tractography Measurement Types" * @param measurementUnitCodes The physical units of the measured value. * DICOM prescribes a code from CID 82 "Units of Measurement". * @param measurement The created measurement, if successful, NULL otherwise * @return EC_Normal if successful, error otherwise */ virtual OFCondition addMeasurement(const CodeSequenceMacro& measurementCode, const CodeSequenceMacro& measurementUnitCodes, TrcMeasurement*& measurement /* result */); /** Add Track Statistic, i.e. statistic that is defined once and where a single * value must be provided for all tracks. * @param typeCode The type of statistic, DICOM prescribes code from CID * 7263 "Diffusion Tractography Measurement Types". * @param typeModifierCode The region of interest of this statistic. DICOM * prescribes code from CID 7464 "General Region of Interest * Measurement Modifiers" * @param unitsCode The physical units of the measured value. DICOM * prescribes a code from CID 82 "Units of Measurement". * @param values The statistical values, one for each track * @param numValues The number of values in statisticValues (must be equal to * number of tracks in this Track Set) * @param statistic Returns the created statistic, if successful. NULL * otherwise * @return Returns EC_Normal if successful, error otherwise */ virtual OFCondition addTrackStatistics(const CodeSequenceMacro& typeCode, const CodeSequenceMacro& typeModifierCode, const CodeSequenceMacro& unitsCode, const Float32* values, const size_t numValues, TrcTracksStatistic*& statistic /* result */); /** Add Track Set Statistic, i.e. a statistical value computed for the whole * Track Set. * @param typeCode The type of statistic, DICOM prescribes code from CID * 7263 "Diffusion Tractography Measurement Types". * @param typeModifierCode The region of interest of this statistic. DICOM * prescribes code from CID 7464 "General Region of Interest * Measurement Modifiers" * @param unitsCode The physical units of the measured value. DICOM * prescribes a code from CID 82 "Units of Measurement". * @param value The statistical value * @param statistic Returns the created statistic, if successful. NULL * otherwise */ virtual OFCondition addTrackSetStatistic(const CodeSequenceMacro& typeCode, const CodeSequenceMacro& typeModifierCode, const CodeSequenceMacro& unitsCode, const Float64 value, TrcTrackSetStatistic*& statistic /* result */); /** Set Track Set Label * @param value Value to be set (single value only) or "" for no value * @param checkValue Check 'value' for conformance with VR (LO) and VM (1) * if enabled * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition setTrackSetLabel(const OFString &value, const OFBool checkValue = OFTrue); /** Set Track Set Description * @param value Value to be set (single value only) or "" for no value * @param checkValue Check 'value' for conformance with VR (UT) and VM (1) * if enabled * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition setTrackSetDescription(const OFString &value, const OFBool checkValue = OFTrue); /** Set Recommended Display CIELab Value * @param L CIELab L component value * @param a CIELab a component value * @param b CIELab b component value * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition setRecommendedDisplayCIELabValue(const Uint16 L, const Uint16 a, const Uint16 b); /** Set Recommended Line Thickness * @param value Value to be set. The units shall be the same as the units * of the coordinate system in which the point coordinates are specified. * @param checkValue Check 'value' for conformance with VR (FL) * if enabled * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition setRecommendedLineThickness(const Float32& value, const OFBool checkValue = OFTrue); /** Set Laterality * @param value Value to be set * @param checkValue Check 'value' for conformance if enabled. Parameter is * not used but present for consistency with other functions. * @return EC_Normal if successful, an error code otherwise */ virtual OFCondition setLaterality(const TrcTypes::E_TrackSetLaterality value, const OFBool checkValue = OFTrue); protected: /** Protected constructor, use create() method to create a new Track Set */ TrcTrackSet(); /** Reads Track statistics from item into dedicated structures * @param source The item to read from, must contain Track Set Statistics * Sequence * @return EC_Normal if reading was successful, error otherwise */ OFCondition readTrackStatistics(DcmItem& source); /** Reads Track Set statistics from item into dedicated structures * @param source The item to read from, must contain Track Statistics * Sequence * @return EC_Normal if reading was successful, error otherwise */ OFCondition readTrackSetStatistics(DcmItem& source); OFCondition readMeasurements(DcmItem& source); /** Reads Tracks from item into dedicated structures * @param source The item to read from, must contain Track Sequence * @return EC_Normal if reading was successful, error otherwise */ OFCondition readTracks(DcmItem& source); /** Write Track Statistics to given item * @param result Returns EC_Normal if writing was successful, error otherwise * or if result has not been EC_Normal when calling * @param destination The destination item to write to. The Track Statistic * Sequence will be written by this method. */ void writeTrackStatistics(OFCondition& result, DcmItem& destination); /** Write Track Statistics to given item * @param result Returns EC_Normal if writing was successful, error otherwise * or if result has not been EC_Normal when calling * @param destination The destination item to write to. The Track Set * Statistic Sequence will be written by this method. */ void writeTrackSetStatistics(OFCondition& result, DcmItem& destination); /** Write Measurements to given item * @param result Returns EC_Normal if writing was successful, error otherwise * or if result has not been EC_Normal when calling * @param destination The destination item to write to. The Measurements * Sequence will be written by this method. * @return Same as parameter "result" */ OFCondition writeMeasurements(OFCondition& result, DcmItem& destination); /** Write Tracks to given item * @param result Returns EC_Normal if writing was successful, error otherwise * or if result has not been EC_Normal when calling * @param destination The destination item to write to. The Tracks Sequence * will be written by this method. * @return Same as parameter "result" */ OFCondition writeTracks(OFCondition& result, DcmItem& destination); /** Check whether measurements have data for all tracks * @return EC_Normal measurement data is complete, TRC_EC_MeasurementDataMissing * otherwise */ OFCondition checkMeasurements(); private: /// Data for all tracks (i.e. content of Track Sequence) OFVector m_Tracks; /// Anatomy code for this Track Set CodeWithModifiers m_Anatomy; /// Measurements for this Track Set OFVector m_Measurements; /// Statistics for Tracks in this Track Set OFVector m_TrackStatistics; /// Statistics for Track Set OFVector m_TrackSetStatistics; /// Code for diffusion acquisition used for this Track Set CodeSequenceMacro m_DiffusionAcquisitionCode; /// Code for diffusion model used for this Track Set CodeSequenceMacro m_DiffusionModelCode; /// Codes for algorithms used to create this Track Set OFVector m_TrackingAlgorithmIdentification; }; #endif // TRCTRACKSET_H