DICOM dataSet & tags classes

This section describes the classes and methods responsible for retrieving and setting the information that composes the DICOM structure, represented by the class imebra::DataSet.

Each individual piece of information is stored into a tag (see imebra::Tag) inside the DICOM structure.

DataSet

class DataSet

This class represents a DICOM dataset.

The information it contains is organized into groups and each group may contain several tags.

You can create a DataSet from a DICOM file by using the CodecFactory::load() function:

In C++:

using namespace imebra;
std::unique_ptr<DataSet> pDataSet(CodecFactory::load("/path/to/file));

In Java:

com.imebra.DataSet dataSet = com.imebra.CodecFactory.load("/path/to/file");

You can also create an empty DataSet that can be filled with data and images and then saved to a DICOM file via CodecFactory::save().

When creating an empty DataSet you should specify the proper transfer syntax in the DataSet constructor.

To retrieve the DataSet’s content, use one of the following methods which give direct access to the tags’ values:

In alternative, you can first retrieve a ReadingDataHandler with getReadingDataHandler() and then access the tag’s content via the handler.

To set the DataSet’s content, use one of the following methods:

The previous methods allow to write just the first item in the tag’s content and before writing wipe out the old tag’s content (all the items). If you have to write more than one item in a tag, retrieve a WritingDataHandler with getWritingDataHandler() and then modify all the tag’s items using the WritingDataHandler.

Public Functions

DataSet()

Construct an empty DICOM dataset with unspecified transfer syntax (which represents the default value “1.2.840.10008.1.2” or “Implicit VR little endian”) and charset “ISO 2022 IR 6”.

Use this method when creating a DataSet that will be embedded as a sequence item.

DataSet(const std::string &transferSyntax)

Construct an empty DICOM dataset with charset “ISO 2022 IR 6” and the desidered transfer syntax.

Parameters
  • transferSyntax: the dataSet’s transfer syntax. The following transfer syntaxes are supported:
    • ”1.2.840.10008.1.2” (Implicit VR little endian)
    • ”1.2.840.10008.1.2.1” (Explicit VR little endian)
    • ”1.2.840.10008.1.2.2” (Explicit VR big endian)
    • ”1.2.840.10008.1.2.5” (RLE compression)
    • ”1.2.840.10008.1.2.4.50” (Jpeg baseline 8 bit lossy)
    • ”1.2.840.10008.1.2.4.51” (Jpeg extended 12 bit lossy)
    • ”1.2.840.10008.1.2.4.57” (Jpeg lossless NH)
    • ”1.2.840.10008.1.2.4.70” (Jpeg lossless NH first order prediction)

DataSet(const std::string &transferSyntax, const charsetsList_t &charsets)

Construct an empty DICOM dataset and specifies the default charsets.

Parameters
  • transferSyntax: the dataSet’s transfer syntax. The following transfer syntaxes are supported:
    • ”1.2.840.10008.1.2” (Implicit VR little endian)
    • ”1.2.840.10008.1.2.1” (Explicit VR little endian)
    • ”1.2.840.10008.1.2.2” (Explicit VR big endian)
    • ”1.2.840.10008.1.2.5” (RLE compression)
    • ”1.2.840.10008.1.2.4.50” (Jpeg baseline 8 bit lossy)
    • ”1.2.840.10008.1.2.4.51” (Jpeg extended 12 bit lossy)
    • ”1.2.840.10008.1.2.4.57” (Jpeg lossless NH)
    • ”1.2.840.10008.1.2.4.70” (Jpeg lossless NH first order prediction)
  • charsets: a list of charsets supported by the DataSet

virtual ~DataSet()

Destructor.

tagsIds_t getTags() const

Returns a list of all the tags stored in the DataSet, ordered by group and tag ID.

Return
an ordered list of the stored Tags

Tag *getTag(const TagId &tagId) const

Retrieve the Tag with the specified ID.

Return
the Tag with the specified ID
Parameters
  • tagId: the ID of the tag to retrieve

Tag *getTagCreate(const TagId &tagId, tagVR_t tagVR)

Retrieve the Tag with the specified ID or create it if it doesn’t exist.

Return
the Tag with the specified ID
Parameters
  • tagId: the ID of the tag to retrieve
  • tagVR: the VR to use for the new tag if one doesn’t exist already

Tag *getTagCreate(const TagId &tagId)

Retrieve the Tag with the specified ID or create it if it doesn’t exist.

Return
the Tag with the specified ID
Parameters
  • tagId: the ID of the tag to retrieve

Image *getImage(size_t frameNumber)

Retrieve an image from the dataset.

Images should be retrieved in order (first frame 0, then frame 1, then frame 2 and so on). Images can be retrieved also in random order but this introduces performance penalties.

Throws DataSetImageDoesntExistError if the requested frame does not exist.

Note
Images retrieved from the DataSet should be processed by the ModalityVOILUT transform, which converts the modality-specific pixel values to values that the application can understand. Consider using getImageApplyModalityTransform() to retrieve the image already processed by ModalityVOILUT.
Return
an Image object containing the decompressed image
Parameters
  • frameNumber: the frame to retrieve (the first frame is 0)

Image *getImageApplyModalityTransform(size_t frameNumber)

Retrieve an image from the dataset and if necessary process it with ModalityVOILUT before returning it.

Images should be retrieved in order (first frame 0, then frame 1, then frame 2 and so on). Images can be retrieved also in random order but this introduces performance penalties.

Throws DataSetImageDoesntExistError if the requested frame does not exist.

Return
an image object containing the decompressed image processed with ModalityVOILUT
Parameters
  • frameNumber: the frame to retrieve (the first frame is 0)

void setImage(size_t frameNumber, const Image &image, imageQuality_t quality)

Insert an image into the dataset.

In multi-frame datasets the images must be inserted in order: first, insert the frame 0, then the frame 1, then the frame 2 and so on.

All the inserted images must have the same transfer syntax and the same properties (size, color space, high bit, bits allocated).

If the images are inserted in the wrong order then the DataSetWrongFrameError exception is thrown.

If the image being inserted has different properties than the ones of the images already in the dataset then the exception DataSetDifferentFormatError is thrown.

Parameters
  • frameNumber: the frame number (the first frame is 0)
  • image: the image
  • quality: the quality to use for lossy compression. Ignored if lossless compression is used

vois_t getVOIs()

Return the list of VOI settings stored in the DataSet.

Each VOI setting includes the center & width values that can be used with the VOILUT transform to highlight different parts of an Image.

Return
a list of VOIDescription objects defined in the DataSet

DataSet *getSequenceItem(const TagId &tagId, size_t itemId)

Retrieve a sequence item stored in a tag.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified sequence item then throws MissingItemError.

Return
the requested sequence item
Parameters
  • tagId: the tag’s id containing the sequence item
  • itemId: the sequence item to retrieve. The first item has an Id = 0

void setSequenceItem(const TagId &tagId, size_t itemId, const DataSet &item)

Set a sequence item.

If the specified Tag does not exist then creates a new one with VR tagVR_t::SQ.

Parameters
  • tagId: the tag’s id in which the sequence must be stored
  • itemId: the sequence item to set. The first item has an Id = 0
  • item: the DataSet to store as a sequence item

LUT *getLUT(const TagId &tagId, size_t itemId)

Retrieve a LUT stored in a sequence item.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified sequence item then throws MissingItemError.

Return
the LUT stored in the requested sequence item
Parameters
  • tagId: the tag’s id containing the sequence that stores the LUTs
  • itemId: the sequence item to retrieve. The first item has an Id = 0

ReadingDataHandler *getReadingDataHandler(const TagId &tagId, size_t bufferId) const

Retrieve a ReadingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified buffer item then throws MissingBufferError.

Return
a ReadingDataHandler object connected to the requested Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

WritingDataHandler *getWritingDataHandler(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Retrieve a WritingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandler is connected to a new buffer which is updated and stored into the tag when WritingDataHandler is destroyed.

Return
a WritingDataHandler object connected to a new Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0
  • tagVR: the tag’s VR

WritingDataHandler *getWritingDataHandler(const TagId &tagId, size_t bufferId)

Retrieve a WritingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

The returned WritingDataHandler is connected to a new buffer which is updated and stored into the tag when WritingDataHandler is destroyed.

Return
a WritingDataHandler object connected to a new Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

ReadingDataHandlerNumeric *getReadingDataHandlerNumeric(const TagId &tagId, size_t bufferId) const

Retrieve a getReadingDataHandlerNumeric object connected to a specific tag’s numeric buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified buffer item then throws MissingItemError.

Return
a ReadingDataHandlerNumeric object connected to the requested Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

ReadingDataHandlerNumeric *getReadingDataHandlerRaw(const TagId &tagId, size_t bufferId) const

Retrieve a getReadingDataHandlerNumeric object connected to a specific tag’s buffer, no matter what the tag’s data type.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified buffer item then throws MissingItemError.

Return
a ReadingDataHandlerNumeric object connected to the requested Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

WritingDataHandlerNumeric *getWritingDataHandlerNumeric(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return
a WritingDataHandlerNumeric object connected to a new Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0
  • tagVR: the tag’s VR

WritingDataHandlerNumeric *getWritingDataHandlerNumeric(const TagId &tagId, size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return
a WritingDataHandlerNumeric object connected to a new Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

WritingDataHandlerNumeric *getWritingDataHandlerRaw(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer. The handler content is cast to bytes.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return
a WritingDataHandlerNumeric object connected to a new Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0
  • tagVR: the tag’s VR

WritingDataHandlerNumeric *getWritingDataHandlerRaw(const TagId &tagId, size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer. The handler content is cast to bytes.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return
a WritingDataHandlerNumeric object connected to a new Tag’s buffer
Parameters
  • tagId: the tag’s id containing the requested buffer
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

bool bufferExists(const TagId &tagId, size_t bufferId)

Check if the specified tag and tag’s buffer exist.

Return
true if the specified tag and tag’s buffer exist, false otherwise

std::int32_t getSignedLong(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as signed long integer (32 bit).

If the tag’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

Return
the tag’s value as a signed 32 bit integer
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer

std::int32_t getSignedLong(const TagId &tagId, size_t elementNumber, std::int32_t defaultValue) const

Retrieve a tag’s value as signed long integer (32 bit).

If the tag’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

If the specified Tag does not exist or it does not contain the specified buffer then returns the default value specified in the parameter.

Return
the tag’s value as a signed 32 bit integer, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist

void setSignedLong(const TagId &tagId, std::int32_t newValue, tagVR_t tagVR)

Write a new signed 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • tagVR: the tag’s type to use when a new tag is created.

void setSignedLong(const TagId &tagId, std::int32_t newValue)

Write a new signed 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag

std::uint32_t getUnsignedLong(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as unsigned long integer (32 bit).

If the tag’s value cannot be converted to an unsigned long integer then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

Return
the tag’s value as an unsigned 32 bit integer
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer

std::uint32_t getUnsignedLong(const TagId &tagId, size_t elementNumber, std::uint32_t defaultValue) const

Retrieve a tag’s value as unsigned long integer (32 bit).

If the tag’s value cannot be converted to an unsigned long integer then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return
the tag’s value as an unsigned 32 bit integer, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist

void setUnsignedLong(const TagId &tagId, std::uint32_t newValue, tagVR_t tagVR)

Write a new unsigned 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag is created using the specified data type (VR).

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • tagVR: the tag’s type to use when a new tag is created.

void setUnsignedLong(const TagId &tagId, std::uint32_t newValue)

Write a new unsigned 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag

double getDouble(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a 64 bit floating point.

If the tag’s value cannot be converted to a floating point value then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

Return
the tag’s value as a 64 bit floating point
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer

double getDouble(const TagId &tagId, size_t elementNumber, double defaultValue) const

Retrieve a tag’s value as a 64 bit floating point.

If the tag’s value cannot be converted to a floating point value then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return
the tag’s value as a 64 bit floating point, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist

void setDouble(const TagId &tagId, double newValue, tagVR_t tagVR)

Write a 64 bit floating point value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • tagVR: the tag’s type to use when a new tag is created.

void setDouble(const TagId &tagId, double newValue)

Write a 64 bit floating point value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag

std::string getString(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a string.

If the tag’s value cannot be converted to a string then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

Return
the tag’s value as a string
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer

std::string getString(const TagId &tagId, size_t elementNumber, const std::string &defaultValue) const

Retrieve a tag’s value as a string.

If the tag’s value cannot be converted to a string then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return
the tag’s value as a string, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist

void setString(const TagId &tagId, const std::string &newString, tagVR_t tagVR)

Write a string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a specific VR.

Parameters
  • tagId: the tag’s id
  • newString: the string to write into the tag
  • tagVR: the tag’s type to use when a new tag is created.

void setString(const TagId &tagId, const std::string &newString)

Write a string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters
  • tagId: the tag’s id
  • newString: the string to write into the tag

std::wstring getUnicodeString(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as an Unicode string.

If the tag’s value cannot be converted to a Unicode string then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

Return
the tag’s value as an unicode string
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer

std::wstring getUnicodeString(const TagId &tagId, size_t elementNumber, const std::wstring &defaultValue) const

Retrieve a tag’s value as an unicode string.

If the tag’s value cannot be converted to a Unicode string then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return
the tag’s value as an unicode string, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist

void setUnicodeString(const TagId &tagId, const std::wstring &newString, tagVR_t tagVR)

Write an unicode string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag is created using the specified VR.

Parameters
  • tagId: the tag’s id
  • newString: the string to write into the tag
  • tagVR: the tag’s type to use when a new tag is created.

void setUnicodeString(const TagId &tagId, const std::wstring &newString)

Write an unicode string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters
  • tagId: the tag’s id
  • newString: the string to write into the tag

Age *getAge(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as Age.

If the tag’s value cannot be converted to Age then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

Return
the tag’s value as Age
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer

Age *getAge(const TagId &tagId, size_t elementNumber, const Age &defaultValue) const

Retrieve a tag’s value as Age.

If the tag’s value cannot be converted to Age then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return
the tag’s value as Age, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer 0
  • defaultValue: the value to return if the tag doesn’t exist

void setAge(const TagId &tagId, const Age &age)

Write an Age string into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag and is created using the VR tagVR_t::AS.

Parameters
  • tagId: the tag’s id
  • age: the Age to write into the tag

Date *getDate(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a Date.

If the tag’s value cannot be converted to a Date then throws DataHandlerConversionError.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not exist then throws MissingItemError.

Return
the tag’s value as a Date
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer 0

Date *getDate(const TagId &tagId, size_t elementNumber, const Date &defaultValue) const

Retrieve a tag’s value as a Date.

If the tag’s value cannot be converted to a date then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return
the tag’s value as a Date, or defaultValue if the tag doesn’t exist
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist

void setDate(const TagId &tagId, const Date &date, tagVR_t tagVR)

Write a Date string into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag and/or buffer are created using the specified data type (VR).

Parameters
  • tagId: the tag’s id
  • date: the Date to write into the tag
  • tagVR: the tag’s type to use when a new tag is created.

void setDate(const TagId &tagId, const Date &date)

Write a Date string into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters
  • tagId: the tag’s id
  • date: the Date to write into the tag

tagVR_t getDataType(const TagId &tagId) const

Return the 2 chars data type (VR) of the specified tag.

Return
the tag’s data type (VR)
Parameters
  • tagId: the id of the tag

Tag

class Tag

This class represents a DICOM tag.

Public Functions

size_t getBuffersCount() const

Returns the number of buffers in the tag.

Return
the number of buffers in the tag

bool bufferExists(size_t bufferId) const

Returns true if the specified buffer exists, otherwise it returns false.

Return
true if the buffer exists, false otherwise
Parameters
  • bufferId: the zero-based buffer’s id the function has to check for

size_t getBufferSize(size_t bufferId) const

Returns the size of a buffer, in bytes.

If the buffer doesn’t exist then throws MissingBufferError.

Return
the buffer’s size in bytes
Parameters
  • bufferId: the zero-based buffer’s id the function has to check for

ReadingDataHandler *getReadingDataHandler(size_t bufferId) const

Retrieve a ReadingDataHandler object connected to a specific buffer.

If the specified buffer does not exist then throws or MissingBufferError.

Return
a ReadingDataHandler object connected to the requested buffer
Parameters
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

WritingDataHandler *getWritingDataHandler(size_t bufferId)

Retrieve a WritingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandler is connected to a new buffer which is updated and stored in the tag when WritingDataHandler is destroyed.

Return
a WritingDataHandler object connected to a new Tag’s buffer
Parameters
  • bufferId: the position where the new buffer has to be stored into the tag. The first buffer position is 0

ReadingDataHandlerNumeric *getReadingDataHandlerNumeric(size_t bufferId) const

Retrieve a ReadingDataHandlerNumeric object connected to the Tag’s numeric buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not contain the specified buffer then throws MissingBufferError.

Return
a ReadingDataHandlerNumeric object connected to the Tag’s buffer
Parameters
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

ReadingDataHandlerNumeric *getReadingDataHandlerRaw(size_t bufferId) const

Retrieve a ReadingDataHandlerNumeric object connected to the Tag’s raw data buffer (8 bit unsigned integers).

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not contain the specified buffer then throws MissingBufferError.

Return
a ReadingDataHandlerNumeric object connected to the Tag’s buffer (raw content represented by 8 bit unsigned integers)
Parameters
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

WritingDataHandlerNumeric *getWritingDataHandlerNumeric(size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to the Tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return
a WritingDataHandlerNumeric object connected to a new Tag’s buffer
Parameters
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

WritingDataHandlerNumeric *getWritingDataHandlerRaw(size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to the Tag’s raw data buffer (8 bit unsigned integers).

If the tag’s VR is not a numeric type then throws std::bad_cast.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return
a WritingDataHandlerNumeric object connected to a new Tag’s buffer (the buffer contains raw data of 8 bit integers)
Parameters
  • bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

StreamReader *getStreamReader(size_t bufferId)

Get a StreamReader connected to a buffer’s data.

Return
the streamReader connected to the buffer’s data.
Parameters
  • bufferId: the id of the buffer for which the StreamReader is required. This parameter is usually 0

StreamWriter *getStreamWriter(size_t bufferId)

Get a StreamWriter connected to a buffer’s data.

Return
the StreamWriter connected to the buffer’s data.
Parameters
  • bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

DataSet *getSequenceItem(size_t dataSetId) const

Retrieve an embedded DataSet.

Sequence tags (VR=SQ) store embedded dicom structures.

Return
the sequence DataSet
Parameters
  • dataSetId: the ID of the sequence item to retrieve. Several sequence items can be embedded in one tag.

bool sequenceItemExists(size_t dataSetId) const

Check for the existance of a sequence item.

Return
true if the sequence item exists, false otherwise
Parameters
  • dataSetId: the ID of the sequence item to check for

void setSequenceItem(size_t dataSetId, const DataSet &dataSet)

Insert a sequence item into the Tag.

Several sequence items can be nested one inside each other. When a sequence item is embedded into a Tag, then the tag will have a sequence VR (VR = SQ).

Parameters
  • dataSetId: the ID of the sequence item
  • dataSet: the DataSet containing the sequence item data

void appendSequenceItem(const DataSet &dataSet)

Append a sequence item into the Tag.

Several sequence items can be nested one inside each other. When a sequence item is embedded into a Tag, then the tag will have a sequence VR (VR = SQ).

Parameters
  • dataSet: the DataSet containing the sequence item data

tagVR_t getDataType() const

Get the tag’s data type.

Return
the tag’s data type

TagId

class TagId

Represents a Dicom tag’s identification.

Public Functions

TagId()

Default constructor.

Initializes the group id and the tag id to 0.

TagId(std::uint16_t groupId, std::uint16_t tagId)

Constructor.

Parameters
  • groupId: the group id
  • tagId: the tag id

TagId(std::uint16_t groupId, std::uint32_t groupOrder, std::uint16_t tagId)

Constructor.

Parameters
  • groupId: the group id
  • groupOrder: old DICOM files may have several groups with the same id. This parameter specifies which of the groups with the same id must be taken into consideration
  • tagId: the tag id

TagId(tagId_t id)

Constructor.

Warning
Very large enumeration classes cause an error in Java, therefore the tagId_t enumeration is not supported in Java.
Parameters
  • id: an enumeration representing a tag group and id

TagId(tagId_t id, std::uint32_t groupOrder)

Constructor.

Parameters
  • id: an enumeration representing a tag group and id
  • groupOrder: old DICOM files may have several groups with the same id. This parameter specifies which of the groups with the same id must be taken into consideration

std::uint16_t getGroupId() const

Retrieve the group id.

Return
the group id

std::uint32_t getGroupOrder() const

Return the group order. Old DICOM files may have several groups with the same id. This value specifies which of the groups with the same id has been taken into consideration.

Return
the group order

std::uint16_t getTagId() const

Retrieve the tag id.

Return
the tag id

ReadingDataHandler

class ReadingDataHandler

The ReadingDataHandler class allows reading the content of a Dicom Tag.

ReadingDataHandler is able to return the Tag’s content as a string, a number, a date/time or an age.

In order to obtain a ReadingDataHandler object for a specific Tag stored in a DataSet, call DataSet::getReadingDataHandler() or Tag::getReadingDataHandler().

The ReadingDataHandler object keeps a reference to the buffer’s memory: the buffer’s memory is never modified but only replaced by a new memory area, therefore the ReadingDataHandler client does not need to worry about other clients modifying the memory being read.

Subclassed by imebra::ReadingDataHandlerNumeric

Public Functions

size_t getSize() const

Returns the number of elements in the Tag’s buffer handled by the data handler.

If the ReadingDataHandler object is related to a buffer that contains strings then it returns the number of strings stored in the buffer. Multiple strings are separated by a separator char.

Return
the number of elements stored in the handled Dicom buffer

tagVR_t getDataType() const

Returns the data type (VR) of the data handled by the data handler.

Return
the data type of the handled data

std::int32_t getSignedLong(size_t index) const

Retrieve a buffer’s value as signed long integer (32 bit).

If the buffer’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

Return
the tag’s value as a signed 32 bit integer
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

std::uint32_t getUnsignedLong(size_t index) const

Retrieve a buffer’s value as an unsigned long integer (32 bit).

If the buffer’s value cannot be converted to an unsigned long integer then throws DataHandlerConversionError.

Return
the tag’s value as an unsigned 32 bit integer
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

double getDouble(size_t index) const

Retrieve a buffer’s value as a double floating point value (64 bit).

If the buffer’s value cannot be converted to a double value then throws DataHandlerConversionError.

Return
the tag’s value as a double floating point value (64 bit)
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

std::string getString(size_t index) const

Retrieve a buffer’s value as an ASCII string.

If the buffer’s value cannot be converted to a string then throws DataHandlerConversionError.

Return
the tag’s value as an ASCII string
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

std::wstring getUnicodeString(size_t index) const

Retrieve a buffer’s value as a Unicode string.

If the buffer’s value cannot be converted to a string then throws DataHandlerConversionError.

Return
the tag’s value as a Unicode string
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

Date getDate(size_t index) const

Retrieve a buffer’s value a date or time.

If the buffer’s value cannot be converted to a date or time then throws DataHandlerConversionError.

Return
the tag’s value as a date or time
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

Age getAge(size_t index) const

Retrieve a buffer’s value as an Age.

If the buffer’s value cannot be converted to an Age then throws DataHandlerConversionError.

Return
the tag’s value as an Age
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()

ReadingDataHandlerNumeric

class ReadingDataHandlerNumeric : public imebra::ReadingDataHandler

Specialized ReadingDataHandler for numeric data types.

Includes few methods that allow accessing the raw memory containing the buffer’s data.

Public Functions

ReadMemory *getMemory() const

Return a ReadMemory object referencing the raw buffer’s data.

Return
a ReadMemory object referencing the raw buffer’s data

size_t data(char *destination, size_t destinationSize) const

Copies the buffer’s raw memory content into the specified buffer.

If the allocated buffer is not large enough then the method doesn’t copy any data and just returns the required buffer’ size.

Java

In Java this method accepts a single parameter (a byte array). The size of the byte array must be equal or greater than the number of bytes stored by the data handler.

Python

In Python this method accepts a single parameter (an array). The size of the array (in bytes) must be equal or greater than the number of bytes stored by the data handler.

Return
the number of bytes to be copied into the pre-allocated buffer
Parameters
  • destination: a pointer to the allocated buffer
  • destinationSize: the size of the allocated buffer

const char *data(size_t *pDataSize) const

Returns a pointer to the buffer’s raw memory content.

The referenced buffer is owned by the ReadingDataHandlerNumeric object and must not be freed by the client.

Return
a pointer to the buffer’s raw memory. The referenced buffer is owned by the ReadingDataHandlerNumeric object and must not be freed by the client.
Parameters
  • pDataSize: a variable that will contain the raw memory’s size in bytes

size_t getUnitSize() const

Returns the number of bytes occupied by the numbers handled by the data handler.

Return
the number of bytes occupied by the numbers handled by the data handler

bool isSigned() const

Returns true if the numbers stored in the buffer are signed, false otherwise.

Return
true if the numbers stored in the buffer are signed, false otherwise

bool isFloat() const

Returns true if the numbers stored in the buffer are floating point numbers, false otherwise.

Return
true if the numbers stored in the buffer are floating point numbers, false otherwise

void copyTo(const WritingDataHandlerNumeric &destination)

Copies the content of the data handler into another data handler, converting the data to the destination handler data type.

Warning
the size of the destination data handler stays unchanged: if the destination too small to contain all the data to be copied then only a part of the data will be copied.
Parameters
  • destination: the destination data handler

WritingDataHandler

class WritingDataHandler

The WritingDataHandler class allows to write the content of a Dicom tag’s buffer.

WritingDataHandler is able to write into the buffer’s content strings, numbers, date/time or ages.

In order to obtain a WritingDataHandler object for a specific tag stored in a DataSet, call DataSet::getWritingDataHandler() or Tag::getWritingDataHandler().

The WritingDataHandler object always works on a new and clean memory area. The buffer’s memory is replaced by the WritingDataHandler memory when the data handler is destroyed.

Subclassed by imebra::WritingDataHandlerNumeric

Public Functions

virtual ~WritingDataHandler()

Destructor: replaces the tag buffer’s memory with the memory created by this WritingDataHandler.

void setSize(size_t elementsNumber)

Resize the memory to contain the specified number of elements.

By default, the WritingDataHandler buffer allocates an empty memory block that must be resized in order to be filled with data.

The type of the contained elements depends on the tag’s VR. The VR can be retrieved with getDataType().

Parameters
  • elementsNumber: the number of elements to store in the buffer.

size_t getSize() const

Retrieve the number of elements that can be stored in the buffer controlled by WritingDataHandler.

The memory size can be changed with setSize().

The type of the contained elements depends on the tag’s VR. The VR can be retrieved with getDataType().

Return
the number of elements that can be stored in the buffer

tagVR_t getDataType() const

Returns the data type (VR) of the data handled by the data handler.

Return
the data type of the handled data

void setSignedLong(size_t index, std::int32_t value)

Write a signed long integer (32 bit).

If the value cannot be converted from a signed long integer then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • value: the value to write

void setUnsignedLong(size_t index, std::uint32_t value)

Write an unsigned long integer (32 bit).

If the value cannot be converted from an unsigned long integer then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • value: the value to write

void setDouble(size_t index, double value)

Write a double floating point value (64 bit).

If the value cannot be converted from a double floating point then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • value: the value to write

void setString(size_t index, const std::string &value)

Write a string.

If the value cannot be converted from a string then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • value: the value to write

void setUnicodeString(size_t index, const std::wstring &value)

Write an Unicode string.

If the value cannot be converted from a Unicode string then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • value: the value to write

void setDate(size_t index, const Date &date)

Write a date and/or a time.

If the value cannot be converted from a Date then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • date: the value to write

void setAge(size_t index, const Age &age)

Write an Age value.

If the value cannot be converted from an Age then throws DataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • age: the value to write

WritingDataHandlerNumeric

class WritingDataHandlerNumeric : public imebra::WritingDataHandler

Specialized WritingDataHandler for numeric data types.

Includes few methods that allow accessing the raw memory containing the buffer’s data.

Public Functions

ReadWriteMemory *getMemory() const

Return a ReadWriteMemory object referencing the raw buffer’s data.

Return
a ReadWriteMemory object referencing the raw buffer’s data

void assign(const char *source, size_t sourceSize)

Copy the content of the specified buffer into the content managed by data handler.

Java

In Java this method accepts a single parameter (a byte array).

Python

In Python this method accepts a single parameter (an array).

Parameters
  • source: a pointer to the source memory buffer
  • sourceSize: the number of bytes to copy and the new memory size

char *data(size_t *pDataSize) const

Returns a pointer to the buffer’s raw memory content.

The referenced buffer is owned by the WritingDataHandlerNumeric object and must not be freed by the client.

Return
a pointer to the buffer’s raw memory. The referenced buffer is owned by the WritingDataHandlerNumeric object and must not be freed by the client
Parameters
  • pDataSize: a variable that will contain the raw memory’s size in bytes

size_t data(char *destination, size_t destinationSize) const

Copies the raw memory content into the specified buffer.

If the allocated buffer is not large enough then the method doesn’t copy any data and just returns the required buffer’ size.

Return
the number of bytes to be copied into the pre-allocated buffer
Parameters
  • destination: a pointer to the allocated buffer
  • destinationSize: the size of the allocated buffer, in bytes

size_t getUnitSize() const

Returns the number of bytes occupied by the numbers handled by the data handler.

Return
the number of bytes occupied by the numbers handled by the data handler

bool isSigned() const

Returns true if the numbers handled by the data handler are signed, false otherwise.

Return
true if the numbers handled by the data handler are signed, false otherwise

bool isFloat() const

Returns true if the numbers stored in the buffer are floating point numbers, false otherwise.

Return
true if the numbers stored in the buffer are floating point numbers, false otherwise

void copyFrom(const ReadingDataHandlerNumeric &source)

Copies data from another data handler, converting the data type if necessary.

The data handler is resized to the same size of the source data handler.

Parameters
  • source: the data handler from which the data must be copied