Transforms classes¶
Introduction¶
This chapter describes the transform classes. Transform classes apply a transform algorithm to an input image and return the result in an output image.
The following classes are described in this chapter:
C++ class |
Objective-C/Swift class |
Description |
---|---|---|
Base class for all the transforms |
||
Apply a sequence of transforms |
||
Apply a presentation VOI or LUT |
||
Describes the VOI’s parameters (center, width, function) |
||
Apply the modality VOI or LUT |
||
Shift the pixels bits |
||
Transform the color space |

Class diagram of the transforms classes¶
Base Transform class¶
Transform¶
C++¶
-
class
Transform
¶ Represents a transform: a transform takes one Image as input, processes it and outputs the processed Image.
Subclassed by imebra::ModalityVOILUT, imebra::TransformHighBit, imebra::TransformsChain, imebra::VOILUT
Public Functions
-
bool
isEmpty
() const¶ Returns true if the transform doesn’t perform any processing (the output image will be identical to the input one).
- Return
true if the Transform doesn’t perform any processing
-
MutableImage
allocateOutputImage
(const Image &inputImage, std::uint32_t width, std::uint32_t height) const¶ Allocate an image ready to accomodate the result of the image processing performed by the runTransform() method.
- Return
an image ready to be passed as outputImage to runTransform()
- Parameters
inputImage
: the image that will be set as the input of the runTransform() methodwidth
: the width of the output imageheight
: the height of the output image
-
void
runTransform
(const Image &inputImage, std::uint32_t inputTopLeftX, std::uint32_t inputTopLeftY, std::uint32_t inputWidth, std::uint32_t inputHeight, MutableImage &outputImage, std::uint32_t outputTopLeftX, std::uint32_t outputTopLeftY) const¶ Run the processing function of the Transform.
- Parameters
inputImage
: the image to use as input
-
bool
Objective-C/Swift¶
-
class
ImebraTransform
: public NSObject¶ Represents a transform: a transform takes one ImebraImage as input, processes it and outputs the processed ImebraImage.
Subclassed by ImebraModalityVOILUT, ImebraTransformHighBit, ImebraTransformsChain, ImebraVOILUT
Public Functions
-
ImebraMutableImage* ImebraTransform::allocateOutputImage:width:height:error:(ImebraImage * pInputImage, unsigned int width, unsigned int height, NSError ** pError)
Allocate an image ready to accomodate the result of the image processing performed by the runTransform() method.
- Return
an image ready to be passed as outputImage to runTransform()
- Parameters
pInputImage
: the image that will be set as the input of the runTransform() methodwidth
: the width of the output imageheight
: the height of the output imagepError
: set to a NSError derived class in case of error
-
void ImebraTransform::runTransform:inputTopLeftX:inputTopLeftY:inputWidth:inputHeight:outputImage:outputTopLeftX:outputTopLeftY:error:(ImebraImage * pInputImage, unsigned int inputTopLeftX, unsigned int inputTopLeftY, unsigned int inputWidth, unsigned int inputHeight, ImebraMutableImage * pOutputImage, unsigned int outputTopLeftX, unsigned int outputTopLeftY, (swift_error(nonnull_error)) __attribute__)
Run the processing function of the ImebraTransform.
- Parameters
inputImage
: the image to use as inputinputTopLeftX
: the horizontal position of the top-left pixel to processinputTopLeftY
: the vertical position of the top-left pixel to processinputWidth
: the horizontal number of pixels to processinputHeight
: the vertical number of pixels to processoutputTopLeftX
: the horizontal position on the output image of the top left processed pixeloutputTopLeftY
: the vertical position on the output image of the top left processed pixelpError
: set to a NSError derived class in case of error
Property
-
property
ImebraTransform::isEmpty
Returns true if the transform doesn’t perform any processing (the output image will be identical to the input one).
-
TransformsChain¶
C++¶
-
class
TransformsChain
: public imebra::Transform¶ The TransformsChain applies a series of Transforms to the input image.
Transforms can be added to the chain by using addTransform().
Public Functions
-
TransformsChain
()¶ Constructor.
-
TransformsChain
(const TransformsChain &source)¶ Copy constructor.
- Parameters
source
: source TransformsChain object
-
Objective-C/Swift¶
-
class
ImebraTransformsChain
: public ImebraTransform¶ ImebraTransformsChain applies a series of ImebraTransforms to the input image.
Transforms can be added to the chain by using addTransform().
Modality and Presentation transforms¶
VOILUT¶
C++¶
-
class
VOILUT
: public imebra::Transform¶ A VOILUT transform enhances the visibility of a specific range of brightness in an image.
The client can use VOILUT in three ways:
by declaring the minimum and maximum values of the pixels that must be visible via the method setCenterWidth()
by declaring a LUT via the method setLUT()
by letting the transform calculate the most appropriate center/width values via the method applyOptimalVOI()
The DataSet may already supply suitable values for the methods setCenterWidth() and setLUT().
In order to retrieve from the DataSet the suggested center/width values, call DataSet.getVOIs().
To get from the DataSet a list of LUTs that can be used with the VOILUT transform use DataSet.getLUT(TagId(tagId_t::VOILUTSequence_0028_3010), X) where X is a 0 base index (the DataSet may provide more than one LUT for the VOILUT transform).
Public Functions
-
VOILUT
(const LUT &lut)¶ Construct a VOILUT transform and specifies the LUT (lookup table) to use in the transform.
- Parameters
lut
: the lookup table to use during the transform
-
VOILUT
(const VOIDescription &voiDescription)¶ Construct a VOILUT transform and specifies the window center, width and function to use during the transform.
- Parameters
voiDescription
: a VOIDescription object specifying the center, width and function
Public Static Functions
-
static VOIDescription
getOptimalVOI
(const Image &inputImage, std::uint32_t topLeftX, std::uint32_t topLeftY, std::uint32_t width, std::uint32_t height)¶ Find the optimal VOI settings for a specific image’s area and apply it with setCenterWidth().
- Parameters
inputImage
: the image to analyzetopLeftX
: the horizontal coordinate of the top-left angle of the area to analyzetopLeftY
: the vertical coordinate of the top-left angle of the area to analyzewidth
: the width of the area to analyzeheight
: the height of the area to analyze
Objective-C/Swift¶
-
class
ImebraVOILUT
: public ImebraTransform¶ A VOILUT transform enhances the visibility of a specific range of brightness in an image.
The client can use VOILUT in three ways:
by declaring the minimum and maximum values of the pixels that must be visible via the method setCenterWidth()
by declaring a LUT via the method setLUT()
by letting the transform calculate the most appropriate center/width values via the method applyOptimalVOI()
ImebraDataSet may already supply suitable values for the methods setCenterWidth() and setLUT().
In order to retrieve from the dataset the suggested center/width values, call ImebraDataSet::getVOIs().
To get from the dataset a list of LUTs that can be used with the VOILUT transform use ImebraDataSet::getLUT(TagId(ImebraTagIdVOILUTSequence_0028_3010), X) where X is a 0 base index (the dataset may provide more than one LUT for the VOILUT transform).
Public Functions
-
id ImebraVOILUT::initWithLUT:(ImebraLUT * lut)
Initializer.
Public Static Functions
-
ImebraVOIDescription* ImebraVOILUT::getOptimalVOI:inputTopLeftX:inputTopLeftY:inputWidth:inputHeight:error:(ImebraImage * pInputImage, unsigned int inputTopLeftX, unsigned int inputTopLeftY, unsigned int inputWidth, unsigned int inputHeight, (swift_error(nonnull_error)) __attribute__)
Find the optimal VOI settings for a specific image’s area and apply it with setCenterWidth().
- Return
an ImebraVOIDescription object describing the optimal VOI parameters
- Parameters
pInputImage
: the image to analyzetopLeftX
: the horizontal coordinate of the top-left angle of the area to analyzetopLeftY
: the vertical coordinate of the top-left angle of the area to analyzewidth
: the width of the area to analyzeheight
: the height of the area to analyzepError
: set to a NSError derived class in case of error
VOIDescription¶
C++¶
-
class
VOIDescription
¶ Stores a VOI description and settings.
The VOIs can be retrieved from a DataSet with DataSet::getVOIs() which returns all the VOIs registered in the DataSet.
Once retrieved, the VOI can be passed to the VOILUT transform that apply the VOI settings to an Image.
Public Functions
-
VOIDescription
(const VOIDescription &source)¶ Copy constructor.
- Parameters
source
: source Date object
-
VOIDescription &
operator=
(const VOIDescription &source)¶ Assign operator.
- Return
a reference to this VOIDescription object
- Parameters
source
: source VOIDescription object
-
VOIDescription
(double center, double width, dicomVOIFunction_t function, const std::string &description)¶ Construct and initializes the VOIDesciption.
- Parameters
center
: the VOI window’s centerwidth
: the VOI windoe’s widthfunction
: the function to use when applying the center/widthdescription
: the VOI description (UTF8 encoded)
-
VOIDescription
(double center, double width, dicomVOIFunction_t function, const std::wstring &descriptionUnicode)¶ Construct and initializes the VOIDesciption.
- Parameters
center
: the VOI window’s centerwidth
: the VOI windoe’s widthfunction
: the function to use when applying the center/widthdescription
: the VOI description (unicode)
-
double
getCenter
() const¶ Returns the VOI center.
- Return
the VOI center
-
double
getWidth
() const¶ Returns the VOI width.
- Return
the VOI width
-
dicomVOIFunction_t
getFunction
() const¶ Returns the VOI function.
- Return
the VOI function
-
std::string
getDescription
() const¶ Returns the VOI description.
- Return
the VOI description (UTF8)
-
std::wstring
getUnicodeDescription
() const¶ Returns the VOI description.
- Return
the VOI description (UCS2 or 4)
-
Objective-C/Swift¶
-
class
ImebraVOIDescription
: public NSObject¶ Specifies an age, in days, weeks, months or years.
Public Functions
-
id ImebraVOIDescription::initWithCenter:width:function:description:(double center, double width, ImebraDicomVOIFunction function, NSString * description)
Constructor.
- Parameters
center
: the VOI window’s centerwidth
: the VOI windoe’s widthfunction
: the function to use when applying the center/widthdescription
: the VOI description (unicode)
Property
-
property
ImebraVOIDescription::center
The VOI window center.
-
property
ImebraVOIDescription::width
The VOI window width.
-
property
ImebraVOIDescription::function
The VOI function.
-
property
ImebraVOIDescription::description
The VOI description.
-
LUT¶
C++¶
-
class
LUT
¶ This class represents Lookup Table.
Objective-C/Swift¶
-
class
ImebraLUT
: public NSObject¶ This class represents Lookup Table.
Public Functions
-
ImebraReadingDataHandlerNumeric *
getReadingDataHandler
()¶ Return a numeric handler for the memory containing the mapped values.
- Return
a reading data handler that points to the mapped values
-
unsigned int ImebraLUT::getMappedValue:(int index)
Return the mapped value for a specific index.
- Return
the mapped value for the requested index
- Parameters
index
: a LUT index
Property
-
property
ImebraLUT::description
Returns the LUT’s description.
-
property
ImebraLUT::bits
Return the number of bits used to store a LUT value.
-
property
ImebraLUT::size
Return the lut’s size (the number of stored values).
-
property
ImebraLUT::firstMappedValue
Return the first LUT index that has a mapped value.
-
ImebraReadingDataHandlerNumeric *
ModalityVOILUT¶
C++¶
-
class
ModalityVOILUT
: public imebra::Transform¶ The ModalityVOILUT transform applies the Modality VOI or LUT to the input image.
The Modality VOI/LUT applies a rescale intercept and a slope to transform the pixel values of the image into values that are meaningful to the application.
For instance, the original pixel values could store a device specific value that has a meaning only when used by the device that generated it: applying the rescale slope/intercept to pixel value converts the original values into optical density or other known measurement units (e.g. Hounsfield).
When the transformation is not linear, then a LUT (lookup table) is applied.
Public Functions
-
ModalityVOILUT
(const DataSet &dataset)¶ Constructor.
- Parameters
dataset
: the DataSet from which the modality VOI or LUT data is retrieved. If the modality VOI/LUT information is stored in a functional group, then first use DataSet::getFunctionalGroupDataSet() to retrieve the sequence item containing the modality VOI/LUT information and pass that item as parameter to this constructor
-
ModalityVOILUT
(const ModalityVOILUT &source)¶ Copy constructor.
- Parameters
source
: source ModalityVOILUT object
-
Objective-C/Swift¶
-
class
ImebraModalityVOILUT
: public ImebraTransform¶ The ImebraModalityVOILUT transform applies the Modality VOI or LUT to the input image.
The Modality VOI/LUT applies a rescale intercept and a slope to transform the pixel values of the image into values that are meaningful to the application.
For instance, the original pixel values could store a device specific value that has a meaning only when used by the device that generated it: applying the rescale slope/intercept to pixel value converts the original values into optical density or other known measurement units (e.g. Hounsfield).
When the transformation is not linear, then a LUT (lookup table) is applied.
Public Functions
-
id ImebraModalityVOILUT::initWithDataSet:(ImebraDataSet * pDataSet)
Initializer.
- Parameters
dataset
: the ImebraDataSet from which the modality VOI or LUT data is retrieved. If the modality VOI/LUT information is stored in a functional group, then first use ImebraDataSet::getFunctionalGroupDataSet() to retrieve the sequence item containing the modality VOI/LUT information and pass that item as parameter to this constructor
-
Rendering transforms¶
TransformHighBit¶
C++¶
-
class
TransformHighBit
: public imebra::Transform¶ The TransformHighBit transform shifts the input image’s values so they match the high-bit settings of the Transform output image.
Public Functions
-
TransformHighBit
()¶ Constructor.
-
TransformHighBit
(const TransformHighBit &source)¶ Copy constructor.
- Parameters
source
: source TransformHighBit object
-
Objective-C/Swift¶
-
class
ImebraTransformHighBit
: public ImebraTransform¶ ImebraTransformHighBit shifts the input image’s values so they match the high-bit settings of the output image.
ColorTransformsFactory¶
C++¶
-
class
ColorTransformsFactory
¶ ColorTransformsFactory has the knowledge about the color spaces supported by the library: it can construct Transform objects that transform images’ content from one color space to another and can return specific information about the supported color spaces.
Public Static Functions
-
static std::string
normalizeColorSpace
(const std::string &colorSpace)¶ Normalize the name of a color space.
DICOM color spaces may contain additional information like the subsampling factor.
This method removes the additional information contained in the color space name and makes it upper-case, so it can be compared with other normalized color space names.
- Return
the normalized color space name
- Parameters
colorSpace
: the color space name to normalize
-
static bool
isMonochrome
(const std::string &colorSpace)¶ Returns true if the specified color space name represents a monochromatic color space.
The method takes care of normalizing the color space before analyzing it.
- Return
true if the normalized color space name represents a monochromatic color space
- Parameters
colorSpace
: the color space to test
-
static bool
isSubsampledX
(const std::string &colorSpace)¶ Returns true if the specified color space name contains additional information that specifies that the pixels are subsampled horizontally.
- Return
true if the color space name specifies that each pixel is subsampled horizontally
- Parameters
colorSpace
: the color space to test for additional information about horizontal subsampling
-
static bool
isSubsampledY
(const std::string &colorSpace)¶ Returns true if the specified color space name contains additional information that specifies that the pixels are subsampled vertically.
- Return
true if the color space name specifies that each pixel is subsampled vertically
- Parameters
colorSpace
: the color space to test for additional information about vertical subsampling
-
static bool
canSubsample
(const std::string &colorSpace)¶ Returns true if the specified color space name supports subsampling information.
- Return
true if subsampling information can be added to the specified color space name
- Parameters
colorSpace
: the color space to test
-
static std::string
makeSubsampled
(const std::string &colorSpace, bool bSubsampleX, bool bSubsampleY)¶ Add subsampling information to the specified color space name.
- Return
the specified color space name with additional information about the pixels subsampling
- Parameters
colorSpace
: the color space to which the subsampling information must be addedbSubsampleX
: true if the pixels are subsampled horizontallybSubsampleY
: true if the pixels are subsampled vertically
-
static std::uint32_t
getNumberOfChannels
(const std::string &colorSpace)¶ Returns the number of color channels necessary for the specified color space.
- Return
the number of color channels necessary to the specified color space
- Parameters
colorSpace
: the color space name
-
static Transform
getTransform
(const std::string &startColorSpace, const std::string &endColorSpace)¶ Returns a Transform object able to transform an image’s content from one color space to another one.
- Return
a Transform object able to transform the image’s content from input color space to output one
- Parameters
startColorSpace
: the color space of the input image’s contentendColorSpace
: the color space of the output image’s content
-
static std::string
Objective-C/Swift¶
-
class
ImebraColorTransformsFactory
: public NSObject¶ ImebraColorTransformsFactory has the knowledge about the color spaces supported by the library: it can construct ImebraTransform objects that transform images’ content from one color space to another and can return specific information about the supported color spaces.
Public Static Functions
-
NSString* ImebraColorTransformsFactory::normalizeColorSpace:(NSString * colorSpace)
Normalize the name of a color space.
DICOM color spaces may contain additional information like the subsampling factor.
This method removes the additional information contained in the color space name and makes it upper-case, so it can be compared with other normalized color space names.
- Return
the normalized color space name
- Parameters
colorSpace
: the color space name to normalize
-
BOOL ImebraColorTransformsFactory::isMonochrome:(NSString * colorSpace)
Returns true if the specified color space name represents a monochromatic color space.
The method takes care of normalizing the color space before analyzing it.
- Return
true if the normalized color space name represents a monochromatic color space
- Parameters
colorSpace
: the color space to test
-
BOOL ImebraColorTransformsFactory::isSubsampledX:(NSString * colorSpace)
Returns true if the specified color space name contains additional information that specifies that the pixels are subsampled horizontally.
- Return
true if the color space name specifies that each pixel is subsampled horizontally
- Parameters
colorSpace
: the color space to test for additional information about horizontal subsampling
-
BOOL ImebraColorTransformsFactory::isSubsampledY:(NSString * colorSpace)
Returns true if the specified color space name contains additional information that specifies that the pixels are subsampled vertically.
- Return
true if the color space name specifies that each pixel is subsampled vertically
- Parameters
colorSpace
: the color space to test for additional information about vertical subsampling
-
BOOL ImebraColorTransformsFactory::canSubsample:(NSString * colorSpace)
Returns true if the specified color space name supports subsampling information.
- Return
true if subsampling information can be added to the specified color space name
- Parameters
colorSpace
: the color space to test
-
NSString* ImebraColorTransformsFactory::makeSubsampled:subSampleX:subSampleY:(NSString * colorSpace, BOOL bSubSampleX, BOOL bSubSampleY)
Add subsampling information to the specified color space name.
- Return
the specified color space name with additional information about the pixels subsampling
- Parameters
colorSpace
: the color space to which the subsampling information must be addedbSubSampleX
: true if the pixels are subsampled horizontallybSubSampleY
: true if the pixels are subsampled vertically
-
unsigned int ImebraColorTransformsFactory::getNumberOfChannels:(NSString * colorSpace)
Returns the number of color channels necessary for the specified color space.
- Return
the number of color channels necessary to the specified color space
- Parameters
colorSpace
: the color space name
-
ImebraTransform* ImebraColorTransformsFactory::getTransform:finalColorSpace:error:(NSString * startColorSpace, NSString * endColorSpace, NSError ** pError)
Returns a ImebraTransform object able to transform an image’s content from one color space to another one.
- Return
a ImebraTransform object able to transform the image’s content from input color space to output one
- Parameters
startColorSpace
: the color space of the input image’s contentendColorSpace
: the color space of the output image’s contentpError
: set if an error occurs
-