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::VOIDescription

ImebraVOIDescription

Describes the VOI’s parameters (center, width, function)

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

Transform(const Transform &source)

Copy constructor.

Parameters

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

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

TransformsChain(const TransformsChain &source)

Copy constructor.

Parameters

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(const VOILUT &source)

Copy constructor.

Parameters
  • source: source VOILUT object

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

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

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

VOIDescription(double center, double width, dicomVOIFunction_t function, const std::string &description)

Construct and initializes the VOIDesciption.

Parameters
  • center: the VOI window’s center

  • width: the VOI windoe’s width

  • function: the function to use when applying the center/width

  • description: 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 center

  • width: the VOI windoe’s width

  • function: the function to use when applying the center/width

  • description: 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 center

  • width: the VOI windoe’s width

  • function: the function to use when applying the center/width

  • description: 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.

Public Functions

LUT(const LUT &source)

Copy constructor.

Parameters
  • source: source LUT object

std::wstring getDescription() const

Returns the LUT’s description.

Return

the LUT’s description

size_t getBits() const

Return the number of bits used to store a LUT value.

Return

the number of bits used to store a mapped value

size_t getSize() const

Return the lut’s size (the number of stored values).

Return

the number of mapped values stored in the lut

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.

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

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

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