Imaging classes

Introduction

The classes described in this chapter are used to store and render images.

The following classes are described in this chapter:

C++ class

Objective-C/Swift class

Description

imebra::Image

ImebraImage

Stores a decompressed image

imebra::MutableImage

ImebraMutableImage

A mutable decompressed image

imebra::Overlay

ImebraOverlay

Stores overlay data

imebra::MutableOverlay

ImebraMutableOverlay

A mutable overlay data

imebra::DrawBitmap

ImebraDrawBitmap

Render an image into a bitmap

Images can be obtained from a DataSet object by calling the getImage or getImageApplyModality methods.

Before being rendered, an image may be processed by one or more Transforms classes.

Image storage

Image

C++

class Image

Represents an immutable DICOM image.

The class manages an uncompressed DICOM image. Images are compressed when they are inserted into the DataSet via DataSet::setImage() and are decompressed when they are referenced by the Image class.

The image is stored in a contiguous area of memory: each channel’s value can occupy 1, 2 or 4 bytes, according to the Image’s data type.

Channels’ values are always interleaved in the Image class, regardless of how they are stored in the DataSet object.

Subclassed by imebra::MutableImage

Public Functions

Image(const Image &source)

Copy constructor.

Parameters
  • source: source Image object

std::uint32_t getWidth() const

Retrieve the image’s width, in pixels.

Return

the image’s width, in pixels

std::uint32_t getHeight() const

Retrieve the image’s height, in pixels.

Return

the image’s height, in pixels

ReadingDataHandlerNumeric getReadingDataHandler() const

Retrieve a ReadingDataHandlerNumeric object referencing the Image’s memory (read only).

The memory referenced by ReadingDataHandlerNumeric contains all the image’s values. The color channels are interleaved.

Return

a ReadingDataHandlerNumeric object referencing the Image’s memory in read-only mode

std::string getColorSpace() const

Retrieve the Image’s color space.

Return

the Image’s color space

std::uint32_t getChannelsNumber() const

Return the number of color channels contained by the image.

Return

the number of color channel contained by the image

bitDepth_t getDepth() const

Return the type of the channels’ values.

Return

the type of the channels’ values

std::uint32_t getHighBit() const

Return the highest bit occupied by the channels’ values.

Return

the highest bit occupied by the channels’ values

Objective-C/Swift

class ImebraImage : public NSObject

Represents a DICOM image.

The class manages an uncompressed DICOM image. Images are compressed when they are inserted into the DataSet via DataSet::setImage() and are decompressed when they are referenced by the Image class.

The image is stored in a contiguous area of memory: each channel’s value can occupy 1, 2 or 4 bytes, according to the Image’s data type.

Channels’ values are always interleaved in the Image class, regardless of how they are stored in the DataSet object.

Subclassed by ImebraMutableImage

Public Functions

ImebraReadingDataHandlerNumeric* ImebraImage::getReadingDataHandler:(NSError ** pError)

Retrieve a ImebraReadingDataHandlerNumeric object referencing the image’s memory (read only).

The memory referenced by ImageReadingDataHandlerNumeric contains all the image’s pixels. The color channels are interleaved.

Return

a ImebraReadingDataHandlerNumeric object referencing the Image’s memory in read-only mode

Property

property ImebraImage::width

Retrieve the image’s width, in pixels.

property ImebraImage::height

Retrieve the image’s height, in pixels.

property ImebraImage::colorSpace

Retrieve the Image’s color space.

property ImebraImage::channelsNumber

Return the number of color channels contained by the image.

property ImebraImage::depth

Return the type of the channels’ values.

property ImebraImage::highBit

Return the highest bit occupied by the channels’ values.

MutableImage

C++

class MutableImage : public imebra::Image

Represents a mutable DICOM image.

The class manages an uncompressed DICOM image. Images are compressed when they are inserted into the DataSet via DataSet::setImage() and are decompressed when they are referenced by the Image class.

The image is stored in a contiguous area of memory: each channel’s value can occupy 1, 2 or 4 bytes, according to the Image’s data type.

Channels’ values are always interleaved in the Image class, regardless of how they are stored in the DataSet object.

Public Functions

MutableImage(std::uint32_t width, std::uint32_t height, bitDepth_t depth, const std::string &colorSpace, std::uint32_t highBit)

Constructor.

The memory for the image is not allocated by the constructor but only when a WritingDataHandler is requested with getWritingDataHandler().

Parameters
  • width: the image width, in pixels

  • height: the image height, in pixels

  • depth: the channel values data types

  • colorSpace: the Image’s color space

  • highBit: the highest bit occupied by the channels’ values

MutableImage(const MutableImage &source)

Copy constructor.

Parameters

WritingDataHandlerNumeric getWritingDataHandler()

Retrieve a WritingDataHandlerNumeric object referencing the Image’s memory (mutable).

The memory referenced by the WritingDataHandlerNumeric object is uninitialized.

When the WritingDataHandlerNumeric is destroyed then the memory managed by the WritingDataHandlerNumeric object replaces the old Image’s memory.

Return

a WritingDataHandlerNumeric object referencing an uninitialized memory buffer that the client has to fill the the image’s data

Objective-C/Swift

class ImebraMutableImage : public ImebraImage

Public Functions

id ImebraMutableImage::initWithWidth:height:depth:colorSpace:highBit:(unsigned int width, unsigned int height, ImebraBitDepth depth, NSString * colorSpace, unsigned int highBit)

Initializer.

The memory for the image is not allocated by the constructor but only when a WritingDataHandler is requested with getWritingDataHandler().

Parameters
  • width: the image width, in pixels

  • height: the image height, in pixels

  • depth: the channel values data types

  • colorSpace: the Image’s color space

  • highBit: the highest bit occupied by the channels’ values

ImebraWritingDataHandlerNumeric* ImebraMutableImage::getWritingDataHandler:(NSError ** pError)

Retrieve a ImebraWritingDataHandlerNumeric object referencing the image’s memory (mutable).

The memory referenced by the ImebraWritingDataHandlerNumeric object is uninitialized.

When the ImebraWritingDataHandlerNumeric object is destroyed then the memory managed by the handler replaces the old image’s memory.

Return

a ImebraWritingDataHandlerNumeric object referencing an uninitialized memory buffer that the client has to fill the the image’s data

Overlay

C++

class Overlay

Represents an immutable DICOM overlay.

Subclassed by imebra::MutableOverlay

Public Functions

Overlay(const Overlay &source)

Copy constructor.

Parameters
  • source: source Image object

std::uint32_t getFirstFrame() const

Retrieve the number of the first frame related to this overlay.

Return

the zero based number of the first frame (Image) related to this overlay

std::uint32_t getFramesCount() const

Returns the number of bitmaps stored in this overlay.

Return

the number of bitmaps stored in the overlay

std::int32_t getZeroBasedOriginX() const

Returns the horizontal position of the overlay bitmap in the DICOM image.

Return

the zero-based horizontal position of the overlay bitmap into the related DICOM image

std::int32_t getZeroBasedOriginY() const

Returns the vertical position of the overlay bitmap in the DICOM image.

Return

the zero-based vertical position of the overlay bitmap into the related DICOM image

std::int32_t getOneBasedOriginX() const

Returns the horizontal position of the overlay bitmap in the DICOM image.

Return

the one-based horizontal position of the overlay bitmap into the related DICOM image

std::int32_t getOneBasedOriginY() const

Returns the vertical position of the overlay bitmap in the DICOM image.

Return

the one-based vertical position of the overlay bitmap into the related DICOM image

overlayType_t getType() const

Return the overlay type.

Return

the overlay type.

std::string getSubType() const

Return the overlay subtype.

Defined Term that identifies the intended purpose of the Overlay Type. See Section C.9.2.1.3 for further explanation.

Return

the overlay subtype.

std::wstring getUnicodeLabel() const

Returns the unicode overlay label.

Return

Unicode overlay label

std::wstring getUnicodeDescription() const

Return the unicode overlay description.

Return

Unicode overlay description

std::string getLabel() const

Return the UTF-8 encoded overlay label.

Return

UTF-8 encoded overlay label

std::string getDescription() const

Return the UTF-8 encoded overlay description.

Return

UTF-8 encoded overlay description

std::uint32_t getROIArea() const

Return the ROI area if present, otherwise throws MissingTagError.

Return

the ROI area in pixels

double getROIMean() const

Return the ROI mean if present, otherwise throws MissingTagError.

Return

the ROI mean

double getROIStandardDeviation()

Return the ROI standard deviation if present, otherwise throws MissingTagError.

Return

the ROI standard deviation

const Image getImage(std::uint32_t frame) const

Return one of the overlay images.

Return

the overlay image

Parameters
  • frame: zero based frame to retrieve

Objective-C/Swift

class ImebraOverlay : public NSObject

Represents an immutable DICOM overlay.

Subclassed by ImebraMutableOverlay

Public Functions

unsigned int ImebraOverlay::getROIArea:((swift_error(nonnull_error)) __attribute__)

Return the ROI area if present, otherwise set pError to ImebraMissingTagError.

Return

the ROI area in pixels

double ImebraOverlay::getROIMean:((swift_error(nonnull_error)) __attribute__)

Return the ROI mean if present, otherwise set pError to ImebraMissingTagError.

Return

the ROI mean value

double ImebraOverlay::getROIStandardDeviation:((swift_error(nonnull_error)) __attribute__)

Return the ROI standard deviation if present, otherwise set pError to ImebraMissingTagError.

Return

the ROI standard deviation

ImebraImage* ImebraOverlay::getImage:error:(unsigned int frameNumber, NSError ** pError)

Return one of the overlay bitmaps if present, otherwise set pError ImebraDataSetImageDoesntExistError.

Return

the requested overlay image

Parameters
  • frameNumber: the number of frame to retrieve (zero based)

  • pError: set to an error class in case of error

Property

property ImebraOverlay::type

The overlay type.

property ImebraOverlay::subType

The overlay subtype.

Defined Term that identifies the intended purpose of the Overlay Type. See Section C.9.2.1.3 for further explanation.

property ImebraOverlay::label

Overlay label.

property ImebraOverlay::description

Overlay description.

property ImebraOverlay::firstFrame

The zero based number of the first frame (Image) related to this overlay,

property ImebraOverlay::framesCount

The number of bitmaps stored in the overlay.

property ImebraOverlay::zeroBasedOriginX

The zero-based horizontal position of the overlay bitmap into the related DICOM image.

property ImebraOverlay::zeroBasedOriginY

The zero-based vertical position of the overlay bitmap into the related DICOM image.

MutableOverlay

C++

class MutableOverlay : public imebra::Overlay

Represents a mutable DICOM overlay.

Public Functions

MutableOverlay(overlayType_t overlayType, const std::string &overlaySubType, std::uint32_t firstFrame, std::int32_t zeroBasedOriginX, std::int32_t zeroBasedOriginY, const std::wstring &label, const std::wstring &description)

Constructor.

Parameters
  • overlayType: the overlay type

  • overlaySubType: the overlay sub-type (defined Term that identifies the intended purpose of the Overlay Type. See Section C.9.2.1.3 for further explanation).

  • firstFrame: the first DICOM image frame related to the overlay

  • zeroBasedOriginX: the overlay zero-based horizontal position within the DICOM image

  • zeroBasedOriginY: the overlay zero-based vertical position within the DICOM image

  • label: the unicode overlay label

  • description: the unicode overlay description

MutableOverlay(overlayType_t overlayType, const std::string &overlaySubType, std::uint32_t firstFrame, std::int32_t zeroBasedOriginX, std::int32_t zeroBasedOriginY, const std::string &label, const std::string &description)

Constructor.

Parameters
  • overlayType: the overlay type

  • overlaySubType: the overlay sub-type (defined Term that identifies the intended purpose of the Overlay Type. See Section C.9.2.1.3 for further explanation).

  • firstFrame: the first DICOM image frame related to the overlay

  • zeroBasedOriginX: the overlay zero-based horizontal position within the DICOM image

  • zeroBasedOriginY: the overlay zero-based vertical position within the DICOM image

  • label: the UTF-8 encoded overlay label

  • description: the UTF-8 encoded overlay description

MutableOverlay(const MutableOverlay &source)

Copy constructor.

Parameters

void setROIArea(std::uint32_t pixels)

Set the number of pixels in the ROI area.

Parameters
  • pixels: number of pixels in the ROI area

void setROIMean(double mean)

Set the mean value of the pixels in the ROI area.

Parameters
  • mean: mean value of the pixels in the ROI area

void setROIStandardDeviation(double standardDeviation)

Set the standard deviation of the value of the pixels in the ROI area.

Parameters
  • standardDeviation: standard deviation of the value of the pixels in the ROI area

void setImage(std::uint32_t frame, const Image &image)

Add a bitmap to the overlay.

Parameters
  • frame: a zero based frame (relative to the overlay frames)

  • image: the image for the overlay

Objective-C/Swift

class ImebraMutableOverlay : public ImebraOverlay

Public Functions

id ImebraMutableOverlay::initWithType:subType:firstFrame:zeroBasedOriginX:zeroBasedOriginY:label:description:(ImebraOverlayType type, NSString * subType, unsigned int firstFrame, int zeroBasedOriginX, int zeroBasedOriginY, NSString * label, NSString * description)

Initializer.

Parameters
  • type: the overlay type

  • subType: the overlay sub type. Defined Term that identifies the intended purpose of the Overlay Type. See Section C.9.2.1.3 for further explanation.

  • firstFrame: first DICOM image related to this overlay (zero-based)

  • zeroBasedOriginX: the zero based horizontal position within the DICOM image

  • zeroBasedOriginY: the zero based vertical position within the DICOM image

  • label: overlay label

  • description: overlay description

void ImebraMutableOverlay::setROIArea:(unsigned int roiArea)

Set the number of pixels in the ROI area.

Parameters
  • roiArea: number of pixels in the ROI area

void ImebraMutableOverlay::setROIMean:(double roiMean)

Set the mean value of the pixels in the ROI area.

Parameters
  • roiMean: mean value of the pixels in the ROI area

void ImebraMutableOverlay::setROIStandardDeviation:(double standardDeviation)

Set the standard deviation of the value of the pixels in the ROI area.

Parameters
  • standardDeviation: standard deviation of the value of the pixels in the ROI area

void ImebraMutableOverlay::setImage:image:error:(unsigned int frameNumber, ImebraImage * image, (swift_error(nonnull_error)) __attribute__)

Add a bitmap to the overlay.

Parameters
  • frameNumber: a zero based frame (relative to the overlay frames)

  • image: the image for the overlay

  • pError: set to an error object if an error occurs

Image rendering

DrawBitmap

C++

class DrawBitmap

DrawBitmap takes care of converting an Image object into an array of bytes that can be displayed by the operating system facilities.

DrawBitmap can apply several transformations to the Image before generating the bitmap.

DrawBitmap applies automatically the necessary color transform and high bit shift in order to obtain a 8 bits per channel RGB image.

Public Functions

DrawBitmap()

Construct a DrawBitmap with no transforms.

The getBitmap() method will not apply any Transform to the Image before generating the bitmap.

DrawBitmap(const Transform &transformsChain)

Construct a DrawBitmap object that always apply the transforms in the specified TransformsChain before calculating the bitmap of the Image in the getBitmap() method.

Parameters
  • transformsChain: the transforms to apply to the Image in the getBitmap() method

DrawBitmap(const DrawBitmap &source)

Copy constructor.

Parameters

virtual ~DrawBitmap()

Destructor.

size_t getBitmap(const Image &image, drawBitmapType_t drawBitmapType, std::uint32_t rowAlignBytes, char *destination, size_t destinationSize)

Apply the transforms defined in the constructor (if any) to the input image, then calculate an array of bytes containing a bitmap that can be rendered by the operating system.

Return

the number of bytes occupied by the bitmap in the pre-allocated buffer. If the number of occupied bytes is bigger than the value of the parameter bufferSize then the method doesn’t generate the bitmap

Parameters
  • image: the image for which the bitmap must be calculated

  • drawBitmapType: the type of bitmap to generate

  • rowAlignBytes: the number of bytes on which the bitmap rows are aligned

  • destination: a pointer to the pre-allocated buffer where getBitmap() will store the generated bitmap

  • destinationSize: the size of the allocated buffer

const Memory getBitmap(const Image &image, drawBitmapType_t drawBitmapType, std::uint32_t rowAlignBytes)

Apply the transforms defined in the constructor (if any) to the input image, then calculate an array of bytes containing a bitmap that can be rendered by the operating system.

Return

a Memory object referencing the buffer containing the generated bitmap

Parameters
  • image: the image for which the bitmap must be calculated

  • drawBitmapType: the type of bitmap to generate

  • rowAlignBytes: the number of bytes on which the bitmap rows are aligned

Objective-C/Swift

class ImebraDrawBitmap : public NSObject

ImebraDrawBitmap takes care of converting an Image object into an array of bytes that can be displayed by the operating system facilities.

ImebraDrawBitmap can apply several transformations to the Image before generating the bitmap.

DrawBitmap applies automatically the necessary color transform and high bit shift in order to obtain a 8 bits per channel RGB image.

Public Functions

id init()

Initializes a ImebraDrawBitmap with no transforms.

The getBitmap() method will not apply any transform to the Image before generating the bitmap (except for the high bit and color space to obtain a 24bpp RGB image).

id ImebraDrawBitmap::initWithTransform:(ImebraTransform * pTransform)

Initializes a ImebraDrawBitmap object that always apply the transform specified in the parameter when calling getBitmap() or getImebraImage().

Parameters
  • pTransform: the transforms to apply to the Image in the getBitmap() method

ImebraMemory* ImebraDrawBitmap::getBitmap:bitmapType:rowAlignBytes:error:(ImebraImage * pImage, ImebraDrawBitmapType drawBitmapType, unsigned int rowAlignBytes, NSError ** pError)

Apply the transforms defined in the constructor (if any) to the input image, then calculate an array of bytes containing a bitmap that can be rendered by the operating system.

Return

a ImebraMemory object containing the buffer containing the generated bitmap

Parameters
  • pImage: the image for which the bitmap must be calculated

  • drawBitmapType: the type of bitmap to generate

  • rowAlignBytes: the number of bytes on which the bitmap rows are aligned

  • pError: set to a NSError derived class in case of error

NSImage* ImebraDrawBitmap::getImebraImage:error:(ImebraImage * pImage, NSError ** pError)

Apply the transforms defined in the constructor (if any) to the input image, then return a NSImage (on OS-X) or an UIImage (on iOS).

Return

a NSImage on OS-X or an UIImage on iOS

Parameters
  • pImage: the image for which the NSImage or UIImage must be calculated

  • pError: set to a NSError derived class in case of error