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

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

source: source Transform object

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

source: source TransformsChain object

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

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

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