DICOM dataSet & tags classes

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

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

ImebraDataSet

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

ImebraTag

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

ImebraTagId

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.

ImebraReadingDataHandler

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.

ImebraReadingDataHandlerNumeric

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.

ImebraWritingDataHandler

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.

ImebraWritingDataHandlerNumeric

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.