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
imebra::Transform ImebraTransform Base class for all the transforms
imebra::TransformsChain ImebraTransformsChain Apply a sequence of transforms
imebra::VOILUT ImebraVOILUT Apply a presentation VOI or LUT
imebra::ModalityVOILUT ImebraModalityVOILUT Apply the modality VOI or LUT
imebra::TransformHighBit ImebraTransformHighBit Shift the pixels bits
imebra::ColorTransformsFactory ImebraColorTransformsFactory Transform the color space
Transforms classes

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

Image *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() method
  • width: the width of the output image
  • height: 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, Image &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

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

ImebraImage* 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() method
  • width: the width of the output image
  • height: the height of the output image
  • pError: 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, ImebraImage * 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 input
  • inputTopLeftX: the horizontal position of the top-left pixel to process
  • inputTopLeftY: the vertical position of the top-left pixel to process
  • inputWidth: the horizontal number of pixels to process
  • inputHeight: the vertical number of pixels to process
  • outputTopLeftX: the horizontal position on the output image of the top left processed pixel
  • outputTopLeftY: the vertical position on the output image of the top left processed pixel
  • pError: 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.

void addTransform(const Transform &transform)

Add a transform to the chain of transforms that will be applied to the input image.

Parameters
  • transform: the Transform to add to the chain of transforms

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

Constructor.

void applyOptimalVOI(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 analyze
  • topLeftX: the horizontal coordinate of the top-left angle of the area to analyze
  • topLeftY: the vertical coordinate of the top-left angle of the area to analyze
  • width: the width of the area to analyze
  • height: the height of the area to analyze

void setCenterWidth(double center, double width)

Set the VOI settings applied by the transform.

Parameters
  • center: the VOI center
  • width: the VOI width

void setLUT(const LUT &lut)

Set the LUT that will be used by the transform to enhance the contrast.

The LUTs to be used for the VOILUT transform are stored in the DataSet’s sequence tagId_t::VOILUTSequence_0028_3010 (group 0x0028, tag 0x3010). Each item in the sequence stores a single LUT.

Use DataSet::getLUT() to retrieve the LUT from the DataSet.

Parameters
  • lut: the LUT to apply

double getCenter() const

Retrieve the VOI center applied by the transform.

Return
the VOI center applied by the transform

double getWidth() const

Retrieve the VOI width applied by the transform.

Return
the VOI width applied by the transform

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(ImebraTagId_t::ImebraVOILUTSequence_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 init()

Initializer.

void ImebraVOILUT::applyOptimalVOI: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().

Parameters
  • pInputImage: the image to analyze
  • topLeftX: the horizontal coordinate of the top-left angle of the area to analyze
  • topLeftY: the vertical coordinate of the top-left angle of the area to analyze
  • width: the width of the area to analyze
  • height: the height of the area to analyze
  • pError: set to a NSError derived class in case of error

void ImebraVOILUT::setCenter:width:(double center, double width)

Set the VOI settings applied by the transform.

Parameters
  • center: the VOI center
  • width: the VOI width

void ImebraVOILUT::setLUT:(ImebraLUT * pLUT)

Set the LUT that will be used by the transform to enhance the contrast.

The LUTs to be used for the VOILUT transform are stored in the dataset’s sequence ImebraTagId_t::ImebraVOILUTSequence_0028_3010 (group 0x0028, tag 0x3010). Each item in the sequence stores a single LUT.

Use ImebraDataSet::getLUT() to retrieve the LUT from the DataSet.

Parameters
  • pLut: the LUT to apply

Property

property ImebraVOILUT::center

Retrieve the VOI center applied by the transform.

property ImebraVOILUT::width

Retrieve the VOI width applied by the transform.

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

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
  • pDataset: the ImebraDataSet from which the modality VOI or LUT data is retrieved

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.

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 added
  • bSubsampleX: true if the pixels are subsampled horizontally
  • bSubsampleY: 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 content
  • endColorSpace: the color space of the output image’s content

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 added
  • bSubSampleX: true if the pixels are subsampled horizontally
  • bSubSampleY: 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 content
  • endColorSpace: the color space of the output image’s content
  • pError: set if an error occurs