DICOM dataSet & tags classes

Introduction

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

The following classes are described in this chapter:

C++ class Objective-C/Swift class Description
imebra::DataSet ImebraDataSet Stored a complete DICOM structure
imebra::Tag ImebraTag Stores a single DICOM tag
imebra::TagId ImebraTagId Identifies a tag
imebra::ReadingDataHandler ImebraReadingDataHandler Read data from a tag
imebra::ReadingDataHandlerNumeric ImebraReadingDataHandlerNumeric Read data from a numeric tag
imebra::WritingDataHandler ImebraWritingDataHandler Write into a tag
imebra::WritingDataHandlerNumeric ImebraWritingDataHandlerNumeric Write into a numeric tag
Data related classes

Class diagram of the data related classes

DataSet is a collection of Tag objects. Each Tag is identified by a TagId.

DataSet supplies several functions that allow to easily read and write the value of the tags however, when advanced functionalities are needed (e.g. when writing several items in one tag that accepts more than one value) then the classes ReadingDataHandler, ReadingDataHandlerNumeric, WritingDataHandler and WritingDataHandlerNumeric should be used.

The difference between ReadingDataHandlerNumeric and ReadingDataHandler (and between WritingDataHandlerNumeric and WritingDataHandler) is that the ‘XXXNumeric’ counterpart supplies functions to access the underlying memory buffer that stores the data, allowing fast processing when dealing with images and large collections of data.

Data storage

DataSet

C++

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

Objective-C/Swift

class ImebraDataSet : public NSObject

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 ImebraDataSet from a DICOM file by using the ImebraCodecFactory::load() function:

NSError* error = nil;
ImebraDataSet* pDataSet = [ImebraCodecFactory load:@"dicomFile.dcm" error:&error];

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

When creating an empty ImebraDataSet you should specify the proper transfer syntax in the init method.

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

  • getImage()
  • getImageApplyModalityTransform()
  • getSequenceItem()
  • getSignedLong()
  • getUnsignedLong()
  • getDouble()
  • getString()
  • getUnicodeString()
  • getAge()
  • getDate()

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

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

  • setImage()
  • setSequenceItem()
  • setSignedLong()
  • setUnsignedLong()
  • setDouble()
  • setString()
  • setUnicodeString()
  • setAge()
  • setDate()

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 ImebraWritingDataHandler with getWritingDataHandler() and then modify all the tag’s items using the ImebraWritingDataHandler.

Public Functions

id init()

Construct an empty DICOM dataset with unspecified transfer syntax (e.g. to be used in a sequence) charset “ISO 2022 IR 6”.

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

id ImebraDataSet::initWithTransferSyntax:(NSString * 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)

id ImebraDataSet::initWithTransferSyntax:charsets:(NSString * transferSyntax, NSArray * pCharsets)

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)
  • pCharsets: a NSArray of NSString specifying the charsets supported by the DataSet

NSArray *getTags()

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

Return
an NSArray containing an ordered list of ImebraTagId objects

ImebraTag* ImebraDataSet::getTag:error:(ImebraTagId * tagId, NSError ** pError)

Retrieve the Tag with the specified ID.

Return
the Tag with the specified ID
Parameters
  • tagId: the ID of the tag to retrieve
  • pError: set if an error occurs

ImebraTag* ImebraDataSet::getTagCreate:tagVR:error:(ImebraTagId * tagId, ImebraTagVR_t tagVR, NSError ** pError)

Retrieve the ImebraTag 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
  • pError: set if an error occurs

ImebraTag* ImebraDataSet::getTagCreate:error:(ImebraTagId * tagId, NSError ** pError)

Retrieve the ImebraTag with the specified ID or create it if it doesn’t exist. Set the proper VR according to the tag ID.

Return
the Tag with the specified ID
Parameters
  • tagId: the ID of the tag to retrieve
  • pError: set if an error occurs

ImebraImage* ImebraDataSet::getImage:error:(unsigned int frameNumber, NSError ** pError)

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.

Set pError and returns nil if the requested image does not exist.

Note
Images retrieved from the ImebraDataSet should be processed by the ImebraModalityVOILUT 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 ImebraModalityVOILUT.
Return
an ImebraImage object containing the decompressed image
Parameters
  • frameNumber: the frame to retrieve (the first frame is 0)
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraImage* ImebraDataSet::getImageApplyModalityTransform:error:(unsigned int frameNumber, NSError ** pError)

Retrieve an image from the dataset and if necessary process it with ImebraModalityVOILUT 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.

Set pError and returns nil if the requested image does not exist.

Return
an ImebraImage object containing the decompressed image processed by ImebraModalityVOILUT (if present)
Parameters
  • frameNumber: the frame to retrieve (the first frame is 0)
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setImage:image:quality:error:(unsigned int frameNumber, ImebraImage * image, ImebraImageQuality_t quality, (swift_error(nonnull_error)) __attribute__)

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 ImebraDataSetWrongFrameError is set in pError.

If the image being inserted has different properties than the ones of the images already in the dataset then the exception ImebraDataSetDifferentFormatError is set in pError.

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
  • pError: a pointer to a NSError pointer which is set when an error occurs

NSArray* ImebraDataSet::getVOIs:(NSError ** pError)

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
an NSArray containing a list of ImebraVOIDescription objects
Parameters
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraDataSet* ImebraDataSet::getSequenceItem:item:error:(ImebraTagId * pTagId, unsigned int itemId, NSError ** pError)

Retrieve a sequence item stored in a tag.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified sequence item then set pError to ImebraMissingItemError.

Return
the requested sequence item
Parameters
  • pTagId: the tag’s id containing the sequence item
  • itemId: the sequence item to retrieve. The first item has an Id = 0
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setSequenceItem:item:dataSet:error:(ImebraTagId * pTagId, unsigned int itemId, ImebraDataSet * pDataSet, (swift_error(nonnull_error)) __attribute__)

Set a sequence item.

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

Parameters
  • pTagId: 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraLUT* ImebraDataSet::getLUT:item:error:(ImebraTagId * pTagId, unsigned int itemId, NSError ** pError)

Retrieve a ImebraLUT stored in a sequence item.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified sequence item then set pError to ImebraMissingItemError.

Return
the LUT stored in the requested sequence item
Parameters
  • pTagId: the tag’s id containing the sequence that stores the LUTs
  • itemId: the sequence item to retrieve. The first item has an Id = 0
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraReadingDataHandler* ImebraDataSet::getReadingDataHandler:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve an ImebraReadingDataHandler object connected to a specific tag’s buffer.

If the specified tag does not exist then sets pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified buffer item then sets pError to ImebraMissingBufferError.

Return
an ImebraReadingDataHandler 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandler* ImebraDataSet::getWritingDataHandler:bufferId:tagVR:error:(ImebraTagId * tagId, unsigned int bufferId, ImebraTagVR_t tagVR, NSError ** pError)

Retrieve an ImebraWritingDataHandler object connected to a specific tag’s buffer and sets its data type (VR).

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

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

Return
a ImebraWritingDataHandler 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandler* ImebraDataSet::getWritingDataHandler:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve a ImebraWritingDataHandler 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 ImebraDicomDictionary.

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

Return
a ImebraWritingDataHandler 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraReadingDataHandlerNumeric* ImebraDataSet::getReadingDataHandlerNumeric:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandlerNumeric 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 set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified buffer item then set pError to ImebraMissingItemError.

Return
a ImebraReadingDataHandlerNumeric 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraReadingDataHandlerNumeric* ImebraDataSet::getReadingDataHandlerRaw:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

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

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified buffer item then set pError to ImebraMissingItemError.

Return
a ImebraReadingDataHandlerNumeric 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandlerNumeric* ImebraDataSet::getWritingDataHandlerNumeric:bufferId:tagVR:error:(ImebraTagId * tagId, unsigned long bufferId, ImebraTagVR_t tagVR, NSError ** pError)

Retrieve a ImebraWritingDataHandlerNumeric 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 ImebraWritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when ImebraWritingDataHandlerNumeric is destroyed.

Return
a ImebraWritingDataHandlerNumeric 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandlerNumeric* ImebraDataSet::getWritingDataHandlerNumeric:bufferId:error:(ImebraTagId * tagId, unsigned long bufferId, NSError ** pError)

Retrieve a ImebraWritingDataHandlerNumeric 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 ImebraDicomDictionary.

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

Return
a ImebraWritingDataHandlerNumeric 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
  • pError: a pointer to a NSError pointer which is set when an error occurs

signed int ImebraDataSet::getSignedLong:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

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 sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s value as a signed 32 bit integer
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • pError: a pointer to a NSError pointer which is set when an error occurs

signed int ImebraDataSet::getSignedLong:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, signed int defaultValue, (swift_error(nonnull_error)) __attribute__)

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 sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return
the tag’s value as a signed 32 bit integer
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setSignedLong:newValue:tagVR:error:(ImebraTagId * tagId, signed int newValue, ImebraTagVR_t tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new signed 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).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

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.
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setSignedLong:newValue:error:(ImebraTagId * tagId, signed int newValue, (swift_error(nonnull_error)) __attribute__)

Write a new signed 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 data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

unsigned int ImebraDataSet::getUnsignedLong:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

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 sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s value as an unsigned 32 bit integer
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • pError: a pointer to a NSError pointer which is set when an error occurs

unsigned int ImebraDataSet::getUnsignedLong:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, unsigned int defaultValue, (swift_error(nonnull_error)) __attribute__)

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 sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return
the tag’s value as an unsigned 32 bit integer
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setUnsignedLong:newValue:tagVR:error:(ImebraTagId * tagId, unsigned int newValue, ImebraTagVR_t tagVR, (swift_error(nonnull_error)) __attribute__)

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).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

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.
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setUnsignedLong:newValue:error:(ImebraTagId * tagId, unsigned int newValue, (swift_error(nonnull_error)) __attribute__)

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 data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

double ImebraDataSet::getDouble:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as a double floating point.

If the tag’s value cannot be converted to double floating point then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s value as a double floating point
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • pError: a pointer to a NSError pointer which is set when an error occurs

double ImebraDataSet::getDouble:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, double defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as a double floating point.

If the tag’s value cannot be converted to double floating point then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return
the tag’s value as a double floating point
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setDouble:newValue:tagVR:error:(ImebraTagId * tagId, double newValue, ImebraTagVR_t tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new double floating point 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).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

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.
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setDouble:newValue:error:(ImebraTagId * tagId, double newValue, (swift_error(nonnull_error)) __attribute__)

Write a new double floating point 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 data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

NSString* ImebraDataSet::getString:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as a string.

If the tag’s value cannot be converted to a string then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s value as a string
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • pError: a pointer to a NSError pointer which is set when an error occurs

NSString* ImebraDataSet::getString:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, NSString * defaultValue, NSError ** pError)

Retrieve a tag’s value as a string.

If the tag’s value cannot be converted to a string then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return
the tag’s value as a string
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setString:newValue:tagVR:error:(ImebraTagId * tagId, NSString * newValue, ImebraTagVR_t tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new 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 data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

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.
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setString:newValue:error:(ImebraTagId * tagId, NSString * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new 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 data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraAge* ImebraDataSet::getAge:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as an ImebraAge object.

If the tag’s value cannot be converted to an ImebraAge object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s value as an ImebraAge object
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraAge* ImebraDataSet::getAge:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, ImebraAge * defaultValue, NSError ** pError)

Retrieve a tag’s value as an ImebraAge object.

If the tag’s value cannot be converted to an ImebraAge object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return
the tag’s value as an ImebraAge object
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setAge:newValue:error:(ImebraTagId * tagId, ImebraAge * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraAge 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 data type (VR) AS.

If the new value cannot be converted to the VR “AS” then sets pError to ImebraDataHandlerConversionError.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraDate* ImebraDataSet::getDate:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as an ImebraDate object.

If the tag’s value cannot be converted to an ImebraDate object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s value as an ImebraDate object
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraDate* ImebraDataSet::getDate:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, ImebraDate * defaultValue, NSError ** pError)

Retrieve a tag’s value as an ImebraDate object.

If the tag’s value cannot be converted to an ImebraDate object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return
the tag’s value as an ImebraDate object
Parameters
  • tagId: the tag’s id
  • elementNumber: the element number within the buffer
  • defaultValue: the value to return if the tag doesn’t exist
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setDate:newValue:tagVR:error:(ImebraTagId * tagId, ImebraDate * newValue, ImebraTagVR_t tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraDate 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).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

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.
  • pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraDataSet::setDate:newValue:error:(ImebraTagId * tagId, ImebraDate * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraDate 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 data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters
  • tagId: the tag’s id
  • newValue: the value to write into the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

ImebraTagVR_t ImebraDataSet::getDataType:error:(ImebraTagId * tagId, (swift_error(nonnull_error)) __attribute__)

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

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return
the tag’s data type (VR)
Parameters
  • tagId: the id of the tag
  • pError: a pointer to a NSError pointer which is set when an error occurs

Tag

C++

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

Objective-C/Swift

class ImebraTag : public NSObject

This class represents a DICOM tag.

Public Functions

unsigned int getBuffersCount()

Returns the number of buffers in the tag.

Return
the number of buffers in the tag

BOOL ImebraTag::bufferExists:(unsigned int bufferId)

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

unsigned int ImebraTag::getBufferSize:error:(unsigned int bufferId, (swift_error(nonnull_error)) __attribute__)

Returns the size of a buffer, in bytes.

If the buffer doesn’t exist then set pError to ImebraMissingBufferError.

Return
the buffer’s size in bytes
Parameters
  • bufferId: the zero-based buffer’s id the function has to check for
  • pError: set to a NSError derived class in case of error

ImebraReadingDataHandler* ImebraTag::getReadingDataHandler:error:(unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandler object connected to a specific buffer.

If the buffer doesn’t exist then set pError to ImebraMissingBufferError.

Return
a ImebraReadingDataHandler object connected to the requested buffer
Parameters
  • bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0
  • pError: set to a NSError derived class in case of error

ImebraWritingDataHandler* ImebraTag::getWritingDataHandler:error:(unsigned int bufferId, NSError ** pError)

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

If the specified buffer does not exist then it creates a new buffer.

Return
a ImebraWritingDataHandler 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
  • pError: set to a NSError derived class in case of error

ImebraReadingDataHandlerNumeric* ImebraTag::getReadingDataHandlerNumeric:error:(unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandlerNumeric 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 tag does not contain the specified buffer then set pError to ImebraMissingBufferError.

Return
a ImebraReadingDataHandlerNumeric object connected to the Tag’s buffer
Parameters
  • bufferId: the buffer to connect to the ImebraReadingDataHandler object. The first buffer has an Id = 0
  • pError: set to a NSError derived class in case of error

ImebraReadingDataHandlerNumeric* ImebraTag::getReadingDataHandlerRaw:error:(unsigned int bufferId, NSError ** pError)

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
  • pError: set to a NSError derived class in case of error

ImebraWritingDataHandlerNumeric* ImebraTag::getWritingDataHandlerNumeric:error:(unsigned int bufferId, NSError ** pError)

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
  • pError: set to a NSError derived class in case of error

ImebraWritingDataHandlerNumeric* ImebraTag::getWritingDataHandlerRaw:error:(unsigned int bufferId, NSError ** pError)

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
  • pError: set to a NSError derived class in case of error

ImebraStreamReader* ImebraTag::getStreamReader:error:(unsigned int bufferId, NSError ** pError)

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
  • pError: set to a NSError derived class in case of error

ImebraStreamWriter* ImebraTag::getStreamWriter:error:(unsigned int bufferId, NSError ** pError)

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
  • pError: set to a NSError derived class in case of error

ImebraDataSet* ImebraTag::getSequenceItem:error:(unsigned int dataSetId, NSError ** pError)

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.
  • pError: set to a NSError derived class in case of error

BOOL ImebraTag::sequenceItemExists:(unsigned int dataSetId)

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 ImebraTag::setSequenceItem:dataSet:error:(unsigned int dataSetId, ImebraDataSet * pDataSet, (swift_error(nonnull_error)) __attribute__)

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
  • pError: set to a NSError derived class in case of error
  • dataSet: the DataSet containing the sequence item data

void ImebraTag::appendSequenceItem:error:(ImebraDataSet * pDataSet, (swift_error(nonnull_error)) __attribute__)

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
  • pError: set to a NSError derived class in case of error

Property

property ImebraTag::dataType

Get the tag’s data type.

Return
the tag’s data type

Data access

The data handler allow to read and write the data stored in the tags.

In order to write data into a tag you can:

The WritingDataHandler has the advantage of being able to write multiple elements in the Tag, while the helper methods in the DataSet can write only the first element.

The WritingDataHandler writes all the data into a new buffer, which replaces the old buffer in the Tag only when the data handler is deleted.

Data related classes

Sequence diagram showing how to use a WritingDataHandler

TagId

C++

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

Objective-C/Swift

class ImebraTagId : public NSObject

Represents a Dicom tag’s identification.

Public Functions

id ImebraTagId::initWithGroup:tag:(unsigned short groupId, unsigned short tagId)

Initializer.

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

id ImebraTagId::initWithId:(ImebraTagId_t tagId)

Initializer.

Parameters
  • id: an enumeration representing a tag group and id

id ImebraTagId::initWithGroup:groupOrder:tag:(unsigned short groupId, unsigned int groupOrder, unsigned short tagId)

Initializer.

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

Property

property ImebraTagId::groupId

Retrieve the group id.

property ImebraTagId::groupOrder

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.

property ImebraTagId::tagId

Retrieve the tag id.

ReadingDataHandler

C++

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()

Objective-C/Swift

class ImebraReadingDataHandler : public NSObject

ImebraReadingDataHandler allows reading the content of a Dicom Tag.

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

In order to obtain a ImebraReadingDataHandler object for a specific ImebraTag stored in a ImebraDataSet, call ImebraDataSet::getReadingDataHandler() or ImebraTag::getReadingDataHandler().

ImebraReadingDataHandler 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 ImebraReadingDataHandlerNumeric

Public Functions

int ImebraReadingDataHandler::getSignedLong:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

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 set pError to ImebraDataHandlerConversionError.

Return
the tag’s value as a signed 32 bit integer
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • pError: set to a NSError derived class in case of error

unsigned int ImebraReadingDataHandler::getUnsignedLong:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

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

If the buffer’s value cannot be converted to a unsigned long integer then set pError to ImebraDataHandlerConversionError.

Return
the tag’s value as an unsigned 32 bit integer
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • pError: set to a NSError derived class in case of error

double ImebraReadingDataHandler::getDouble:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

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

If the buffer’s value cannot be converted to a double floating point then set pError to ImebraDataHandlerConversionError.

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()
  • pError: set to a NSError derived class in case of error

NSString* ImebraReadingDataHandler::getString:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as a string.

If the buffer’s value cannot be converted to a string then set pError to ImebraDataHandlerConversionError.

Return
the tag’s value as a string
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • pError: set to a NSError derived class in case of error

ImebraDate* ImebraReadingDataHandler::getDate:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as date or time.

If the buffer’s value cannot be converted to a date or time then set pError to ImebraDataHandlerConversionError.

Return
the tag’s value as a date or time
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • pError: set to a NSError derived class in case of error

ImebraAge* ImebraReadingDataHandler::getAge:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as an age.

If the buffer’s value cannot be converted to an age then set pError to ImebraDataHandlerConversionError.

Return
the tag’s value as an Age
Parameters
  • index: the element number within the buffer. Must be smaller than getSize()
  • pError: set to a NSError derived class in case of error

Property

property ImebraReadingDataHandler::size

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

If the ImebraReadingDataHandler 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.

ReadingDataHandlerNumeric

C++

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 copied into the pre-allocated buffer, or the desired size of destination if destinationSize is smaller than the return value
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

Objective-C/Swift

class ImebraReadingDataHandlerNumeric : public ImebraReadingDataHandler

Specialized ImebraReadingDataHandler for numeric data types.

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

Public Functions

ImebraReadMemory* ImebraReadingDataHandlerNumeric::getMemory:((swift_error(nonnull_error)) __attribute__)

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

Return
a ReadMemory object referencing the raw buffer’s data
Parameters
  • pError: set to a NSError derived class in case of error

void ImebraReadingDataHandlerNumeric::copyTo:error:(ImebraWritingDataHandlerNumeric * destination, (swift_error(nonnull_error)) __attribute__)

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
  • pError: set to a NSError derived class in case of error
  • destination: the destination data handler

Property

property ImebraReadingDataHandlerNumeric::unitSize

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

property ImebraReadingDataHandlerNumeric::isSigned

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

property ImebraReadingDataHandlerNumeric::isFloat

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

WritingDataHandler

C++

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

Objective-C/Swift

class ImebraWritingDataHandler : public NSObject

ImebraWritingDataHandler allows to write the content of a Dicom tag’s buffer.

ImebraWritingDataHandler is able to write strings, numbers, date/time or ages.

In order to obtain a ImebraWritingDataHandler object for a specific tag call ImebraDataSet::getWritingDataHandler() or ImebraTag::getWritingDataHandler().

The ImebraWritingDataHandler object always works on a new and clean memory area. Once the data has been written into the data handler then call commit (ImebraWritingDataHandler) in order to commit the data. The data is committed also when the data handler is deallocated.

Once the data has been committed then the data handler does not respond to further data modifications.

Subclassed by ImebraWritingDataHandlerNumeric

Public Functions

void ImebraWritingDataHandler::setSignedLong:newValue:error:(unsigned int index, int value, (swift_error(nonnull_error)) __attribute__)

Write a signed long integer (32 bit).

If the value cannot be converted from a signed long integer then set pError to ImebraDataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than size()
  • value: the value to write
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setUnsignedLong:newValue:error:(unsigned int index, unsigned int value, (swift_error(nonnull_error)) __attribute__)

Write an unsigned long integer (32 bit).

If the value cannot be converted from an unsigned long integer then set pError to ImebraDataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than size()
  • value: the value to write
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setDouble:newValue:error:(unsigned int index, double value, (swift_error(nonnull_error)) __attribute__)

Write a double floating point value (64 bit).

If the value cannot be converted from a double floating point then set pError to ImebraDataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than size()
  • value: the value to write
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setString:newValue:error:(unsigned int index, NSString * value, (swift_error(nonnull_error)) __attribute__)

Write a string.

If the value cannot be converted from a string then set pError to ImebraDataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than size()
  • value: the value to write
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setDate:newValue:error:(unsigned int index, ImebraDate * value, (swift_error(nonnull_error)) __attribute__)

Write a date and/or a time.

If the value cannot be converted from a Date then set pError to ImebraDataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than size()
  • value: the value to write
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setAge:newValue:error:(unsigned int index, ImebraAge * value, (swift_error(nonnull_error)) __attribute__)

Write an Age value.

If the value cannot be converted from an Age then set pError to ImebraDataHandlerConversionError.

Parameters
  • index: the element number within the buffer. Must be smaller than size()
  • value: the value to write
  • pError: set to a NSError derived class in case of error

void commit()

Commit the changes to the handler’s memory.

Property

property ImebraWritingDataHandler::size

Resize the memory to contain the specified number of elements or return the current number of elements when read.

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

WritingDataHandlerNumeric

C++

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

Objective-C/Swift

class ImebraWritingDataHandlerNumeric : public ImebraWritingDataHandler

Specialized ImebraWritingDataHandler for numeric data types.

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

Public Functions

ImebraReadWriteMemory* ImebraWritingDataHandlerNumeric::getMemory:(NSError ** pError)

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

Return
a ImebraReadWriteMemory object referencing the raw buffer’s data
Parameters
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandlerNumeric::assign:error:(NSData * pSource, (swift_error(nonnull_error)) __attribute__)

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

Parameters
  • pSource: a pointer to the source memory buffer
  • pError: set to a NSError derived class in case of error

void ImebraWritingDataHandlerNumeric::copyFrom:error:(ImebraReadingDataHandlerNumeric * pSource, (swift_error(nonnull_error)) __attribute__)

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
  • pSource: the data handler from which the data must be copied
  • pError: set to a NSError derived class in case of error

Property

property ImebraWritingDataHandlerNumeric::unitSize

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

property ImebraWritingDataHandlerNumeric::isSigned

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

property ImebraWritingDataHandlerNumeric::isFloat

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