DCMTK Version 3.7.0 OFFIS DICOM Toolkit

dcmtract: a library for working with tractography results

This module contains classes to deal with DICOM Tractography Results objects. It is able to create, load and access the contained fiber tracks and the related meta information.

The module fully supports Measurements and Statistics (on a per-track and track set) basis as defined in the standard.

Several checks (as possible) make sure that only valid Tractography objects can be written. However, this module is not meant to modify existing Tractography Result objects but only to create them from scratch. This means that loading a file and then modify it may lead to inconsistent DICOM objects when saved.

This module makes heavy use of the dcmiod module for managing common IOD attributes as found in the Patient, General Study or General Series Module.

The main class of this module is:

- TrcTractographyResults

# Examples

The following (complete) example shows how to load a DICOM Tractography Results object and dump an overview of the contained data:

#include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
#include "dcmtk/dcmtract/trctractographyresults.h"
#include "dcmtk/dcmtract/trctrack.h"
// Main routine of test app
int main(int argc, char *argv[])
{
if (argc < 2)
{
CERR << "Usage: read <inputfile>" << OFendl;
return 1;
}
OFCondition result;
TrcTractographyResults *trc = NULL;
result = TrcTractographyResults::loadFile(argv[1], trc);
if (result.bad())
{
CERR << "Unable to load Tractography Results file: " << result.text();
return 1;
}
OFString val;
trc->getPatient().getPatientName(val);
COUT << "Patient Name: " << val << OFendl;
trc->getStudy().getStudyInstanceUID(val);
COUT << "Study : " << val << OFendl;
trc->getSeries().getSeriesInstanceUID(val);
COUT << "Series : " << val << OFendl;
trc->getSOPCommon().getSOPInstanceUID(val);
COUT << "Instance : " << val << OFendl;
COUT << "-------------------------------------------------------------------------" << OFendl;
size_t numTrackSets = trc->getNumberOfTrackSets();
COUT << "Track Sets (total: " << numTrackSets << ")" << OFendl;
OFVector<TrcTrackSet*>& sets = trc->getTrackSets();
for (size_t ts = 0; ts < numTrackSets; ts++)
{
size_t numTracks = sets[ts]->getNumberOfTracks();
COUT << " Track Set #" << ts << ": " << numTracks << " Tracks, "
<< sets[ts]->getNumberOfTrackSetStatistics() << " Track Set Statistics, "
<< sets[ts]->getNumberOfTrackStatistics() << " Track Statistics, "
<< sets[ts]->getNumberOfMeasurements() << " Measurements " << OFendl;
for (size_t t = 0; t < numTracks; t++)
{
TrcTrack* track = sets[ts]->getTracks()[t];
const Float32* vals = NULL;
size_t numPoints = track->getTrackData(vals);
COUT << " Track #" << t << "'s first 3/" << numTracks << " points: ";
for (size_t v = 0; (v < 3) && (v < numPoints); v++)
{
COUT << "(" << vals[v] << "," << vals[v+1] << "," << vals[v+2] << ") " ;
}
COUT << OFendl;
}
}
delete trc;
return 0;
}
DcmIODCommon::getPatient
IODPatientModule & getPatient()
Get Patient Module.
DcmIODCommon::getSeries
IODGeneralSeriesModule & getSeries()
Get Series Module.
DcmIODCommon::getSOPCommon
IODSOPCommonModule & getSOPCommon()
Get SOP Common Module.
DcmIODCommon::getStudy
IODGeneralStudyModule & getStudy()
Get General Study Module.
IODGeneralSeriesModule::getSeriesInstanceUID
virtual OFCondition getSeriesInstanceUID(OFString &value, const signed long pos=0) const
Get series instance UID.
IODGeneralStudyModule::getStudyInstanceUID
virtual OFCondition getStudyInstanceUID(OFString &value, const signed long pos=0) const
Get Study Instance UID.
IODPatientModule::getPatientName
virtual OFCondition getPatientName(OFString &value, const signed long pos=0) const
Get Patient's Name.
IODSOPCommonModule::getSOPInstanceUID
virtual OFCondition getSOPInstanceUID(OFString &value, const signed long pos=0) const
Get SOP Instance UID.
OFCondition
General purpose class for condition codes.
Definition: ofcond.h:177
OFCondition::bad
OFBool bad() const
check if the status is not OK, i.e. error or failure.
Definition: ofcond.h:322
OFCondition::text
const char * text() const
get a human readable text representation of this error code.
Definition: ofcond.h:297
OFString
a simple string class that implements a subset of std::string.
Definition: ofstring.h:76
OFVector< TrcTrackSet * >
TrcTrack
Class representing a Track of of the "Tractography Results" IOD.
Definition: trctrack.h:36
TrcTrack::getTrackData
virtual size_t getTrackData(const Float32 *&data) const
Get Track Data.
TrcTractographyResults
Class representing an object of the "Tractography Results" object IOD.
Definition: trctractographyresults.h:42
TrcTractographyResults::getNumberOfTrackSets
virtual size_t getNumberOfTrackSets()
Returns number of Track Sets in Tractography Results object.
TrcTractographyResults::loadFile
static OFCondition loadFile(const OFString &filename, TrcTractographyResults *&tractography)
Load Tractography Results object from a file.
TrcTractographyResults::getTrackSets
virtual OFVector< TrcTrackSet * > & getTrackSets()
Return Track Sets (from Tractography Results Module)

The following (complete) example demonstrates creation of a minimal Tractography Results object (single TrackSet with one Track and no Statistics or Measurements). All IDs, UIDs and Track values are, of course, just meaningless examples:

#include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
#include "dcmtk/dcmtract/trctractographyresults.h"
// Main routine of test app
int main(int argc, char *argv[])
{
// Create tractography results object
OFCondition result;
// Instance Number, Label, Description, Creator's Name
ContentIdentificationMacro id("1", "MINI_TRACT", "Minimal Tractography object for demonstration", "Open Connections GmbH");
// Manufacturer, model name, serial number, software version(s)
IODEnhGeneralEquipmentModule::EquipmentInfo equipment("Open Connections Gmbh", "dcmtract library", "0815", OFFIS_DCMTK_VERSION_STRING);
IODReferences refs;
// We need at least one image reference this Tractography Results object is based on.
// We provide: Patient ID, Study Instance UID, Series Instance UID, SOP Instance UID, SOP Class UID
IODImageReference* ref = new IODImageReference("PAT_ID_4711", "1.2.3", "4.5.6", "7.8.9", UID_MRImageStorage);
refs.add(ref);
OFString contentDate = "20160601";
OFString contentTime = "120000";
TrcTractographyResults *trc = NULL;
TrcTractographyResults::create(id, contentDate, contentTime, equipment, refs, trc);
// Create track set
CodeWithModifiers anatomy;
anatomy.set("T-A0095", "SRT", "White matter of brain and spinal cord");
// Every CodeSequenceMacro has: Code Value, Coding Scheme Designator, Code Meaning
CodeSequenceMacro diffusionModel("113231", "DCM", "Single Tensor");
CodeSequenceMacro algorithmId("113211", "DCM", "Deterministic");
TrcTrackSet *set = NULL;
trc->addTrackSet("First and last Track Set", "Mini description", anatomy, diffusionModel, algorithmId, set);
// Create track
Uint16 cieLabColor[3]; // color the whole track with this color; we use some blue
cieLabColor[0] = 30000; // L
cieLabColor[1] = 0 ; // a
cieLabColor[2] = 0 ; // b
Float32 pointData[30]; // actual data, 10 data points with x,y,z coordinates
for (size_t f = 0; f < 10; f++)
{
// x coordinate, varies
pointData[f*3] = f;
// static y coordinate
pointData[f*3+1] = 1;
// static z coordinate
pointData[f*3+2] = 2;
}
TrcTrack* track = NULL;
set->addTrack(pointData, 10, cieLabColor, 1 /* numColors */, track);
// Frame of Reference is required; could be the same as from related MR series
trc->getFrameOfReference().setFrameOfReferenceUID("10.11.12");
// Set some optional data
trc->getPatient().setPatientID("4711");
trc->getPatient().setPatientName("Doe^John");
trc->getSeries().setSeriesDescription("This is just a test series with a single Tractography Results object inside");
// Save file
trc->saveFile("/tmp/create_demo.dcm");
delete trc;
return 0;
}
CodeSequenceMacro
Class representing a Code Sequence Macro.
Definition: iodmacro.h:41
CodeSequenceMacro::set
virtual OFCondition set(const OFString &value, const OFString &scheme, const OFString &meaning, const OFString &schemeVersion="", const OFBool checkValue=OFTrue, const OFBool autoTag=OFTrue)
Set all values in this class conveniently.
CodeWithModifiers
Code with Modifier(s).
Definition: iodmacro.h:277
ContentIdentificationMacro
Content Identification Macro.
Definition: iodmacro.h:968
DcmIODCommon::getFrameOfReference
IODFoRModule & getFrameOfReference()
Get Frame of Reference Module.
IODFoRModule::setFrameOfReferenceUID
virtual OFCondition setFrameOfReferenceUID(const OFString &value, const OFBool checkValue=OFTrue)
Set Frame of Reference UID.
IODGeneralSeriesModule::setSeriesDescription
virtual OFCondition setSeriesDescription(const OFString &value, const OFBool checkValue=OFTrue)
Set Series Description.
IODImageReference
Class representing a reference to an image.
Definition: iodreferences.h:153
IODPatientModule::setPatientID
virtual OFCondition setPatientID(const OFString &value, const OFBool checkValue=OFTrue)
Set Patient ID.
IODPatientModule::setPatientName
virtual OFCondition setPatientName(const OFString &value, const OFBool checkValue=OFTrue)
Set Patient's Name.
IODReferences
Class that holds a set of IODReference instances (or its sub classes) and offers helper functionality...
Definition: iodreferences.h:291
IODReferences::add
virtual OFBool add(IODReference *ref)
Add reference to this set of references.
TrcTrackSet
Class representing a Track Set within the Tractography Results IOD.
Definition: trctrackset.h:46
TrcTrackSet::addTrack
virtual OFCondition addTrack(const Float32 *pointData, const size_t numPoints, const Uint16 *recommendedCIELabColors, const size_t numColors, TrcTrack *&result)
Add track to Track Set.
TrcTractographyResults::saveFile
virtual OFCondition saveFile(const OFString &filename, const E_TransferSyntax writeXfer=EXS_LittleEndianExplicit)
Save current object to given filename.
TrcTractographyResults::create
static OFCondition create(const ContentIdentificationMacro &contentIdentification, const OFString &contentDate, const OFString &contentTime, const IODEnhGeneralEquipmentModule::EquipmentInfo &equipment, const IODReferences &imageReferences, TrcTractographyResults *&result)
Create new Tractography Results object.
TrcTractographyResults::addTrackSet
virtual OFCondition addTrackSet(const OFString &trackSetLabel, const OFString &trackSetDescription, const CodeWithModifiers &anatomyCode, const CodeSequenceMacro &diffusionModelCode, const AlgorithmIdentificationMacro &algoIdentCode, TrcTrackSet *&trackSet)
Add Track Set to object.
OFFIS_DCMTK_VERSION_STRING
#define OFFIS_DCMTK_VERSION_STRING
DCMTK version number (as string) for this release.
Definition: dcuid.h:354
IODEnhGeneralEquipmentModule::EquipmentInfo
Convenient struct containing all information required for setting enhanced equipment information (for...
Definition: modenhequipment.h:45

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1