Display module
#include "diplib/display.h"
dip::ImageDisplay class

Encapsulates state of an image in a display window, and provides the functionality for converting the image to a form suitable for display.

Contents

An object is created for a particular image; the image cannot be replaced. Different display options can then be set. When the dip::ImageDisplay::Output method is called, a 1D or 2D, grey-value or RGB, UINT8 image is prepared for display. A const reference to this image is returned. The image is updated every time the Output method is called, not when display options are set. The display options are designed to be settable by a user using the image display window.

For a scalar input image, the output is always scalar (grey-value). For a color image, if it can be converted to sRGB, and RGB output image is produced. For other tensor images, an RGB image is also produced, the user can select which tensor element is shown in each of the three color channels. Note that for color images, the non-linear sRGB color space is used for display, linear RGB images are gamma-corrected in this way to improve display.

See the dipimage/private/imagedisplay.cpp file implementing the MATLAB interface to this class, and the dipimage/dipshow.m function, for an example of how this can be used.

Constructors, destructors, assignment and conversion operators

ImageDisplay(dip::Image const& image, dip::ColorSpaceManager* colorSpaceManager = nullptr, dip::ExternalInterface* externalInterface = nullptr) explicit
The constructor takes an image with at least 1 dimension. more...

Classes

struct Limits
Intensity mapping limits more...

Enums

enum class ComplexMode: uint8
Enumerator for the complex mapping mode more...
enum class MappingMode: uint8
Enumerator for the intensity mapping mode more...
enum class ProjectionMode: uint8
Enumerator for the projection mode more...

Functions

auto Dimensionality() const -> dip::uint
Get the image dimensionality.
auto GetBlueTensorElement() const -> dip::sint
Get the tensor element to be shown in the blue channel.
auto GetComplexMode() const -> dip::String
Get the current complex to real mapping mode.
auto GetCoordinates() const -> dip::UnsignedArray const&
Get the current coordinates.
auto GetDirection() const -> std::pair<dip::uint, dip::uint>
Get the projection/slicing direction. The two values returned are identical when output is 1D.
auto GetGlobalStretch() const -> bool
Get the current global stretch mode.
auto GetGreenTensorElement() const -> dip::sint
Get the tensor element to be shown in the green channel.
auto GetLimits(bool compute) -> dip::ImageDisplay::Limits
Gets the image intensity range (that selected with "lin") for the current slicing and complex mapping modes. If compute is true, it computes them if they’re not yet computed.
auto GetMappingMode() const -> dip::String
Get the current intensity mapping mode.
auto GetOrthogonal() const -> dip::UnsignedArray const&
Returns the array of dimensions orthogonal to those returned by dip::ImageDisplay::GetDirection. These are the dimensions not displayed.
auto GetProjectionMode() const -> dip::String
Get the current projection mode.
auto GetRange() const -> dip::ImageDisplay::Limits
Get the current intensity range.
auto GetRedTensorElement() const -> dip::sint
Get the tensor element to be shown in the red channel.
auto GetSizes() const -> dip::UnsignedArray const&
Get the image sizes.
auto Input() const -> dip::Image const&
Retrieves a reference to the input image.
auto MapSinglePixel(dip::Image::Pixel const& input) -> dip::Image::Pixel
Puts a single pixel through the same mapping the image will go through to become dip::ImageDisplay::Output.
auto OutIsDirty() const -> bool
Returns true if the next call to dip::ImageDisplay::Output will yield a different result from the previous one. That is, the display needs to be redrawn.
auto Output() -> dip::Image const&
Retrieves a reference to the output image. more...
auto Pixel(dip::uint x, dip::uint y = 0) -> dip::Image::Pixel
Gets input image intensities at a given 2D point (automatically finds corresponding nD location). In case of a 1D dip::ImageDisplay::Output, y is ignored.
void SetComplexMode(dip::ImageDisplay::ComplexMode complexMode)
Sets the complex to real mapping mode. Has no effect when projection mode is set to "max", or for non-complex images.
void SetComplexMode(dip::String const& complexMode)
Sets the complex to real mapping mode. Has no effect when projection mode is set to "max", or for non-complex images. more...
void SetCoordinates(dip::UnsignedArray coordinates)
Sets the current coordinates. This affects the slice displayed.
void SetDirection(dip::uint dim1, dip::uint dim2)
Sets the projection/slicing direction, as the two image dimensions to show along the x and y axis of the 2D display. If dim1==dim2, a 1D output is produced.
void SetGlobalStretch(bool globalStretch)
Sets the global stretch mode. Has no effect on 2D images or when the projection mode is not "slice"
void SetGlobalStretch(dip::String const& globalStretch)
Sets the global stretch mode. Has no effect on 2D images or when the projection mode is not "slice" more...
void SetMappingMode(dip::ImageDisplay::MappingMode mappingMode)
Sets the intensity mapping mode. Has no effect for binary images.
void SetProjectionMode(dip::ImageDisplay::ProjectionMode projectionMode)
Sets the projection mode. Has no effect if image dimensionality is equal to projection dimensionality.
void SetProjectionMode(dip::String const& projectionMode)
Sets the projection mode. Has no effect if image dimensionality is equal to projection dimensionality. more...
void SetRange(dip::ImageDisplay::Limits range)
Sets the range of intensities to be mapped to the output range. Forces intensity mapping mode to linear. Has no effect for binary images.
void SetRange(dip::String const& range)
Sets the mapping mode and the range of intensities to be mapped to the output range. Has no effect for binary images. more...
void SetTensorElements(dip::sint red, dip::sint green = -1, dip::sint blue = -1)
Sets the tensor element to be shown in each of the three output channels. more...
auto SizeIsDirty() const -> bool
Returns true if the next call to dip::ImageDisplay::Output will yield an output of a different size. That is, the slicing direction has changed, and this yields a change in sizes.
auto Slice() -> dip::Image const&
Retrieves a reference to the raw slice image. more...
auto SliceIsDirty() const -> bool
Returns true if the next call to dip::ImageDisplay::Output will yield a different slice

Class documentation

struct Limits

Intensity mapping limits

Variables
dip::dfloat lower This value is mapped to 0.
dip::dfloat upper This value is mapped to 255.

Enum documentation

enum class ProjectionMode: uint8

Enumerator for the projection mode

Enumerators
SLICE = 0 A slice is prepared for display
MAX = 1 The max projection is prepared for display
MEAN = 2 The mean projection is prepared for display

enum class ComplexMode: uint8

Enumerator for the complex mapping mode

Enumerators
MAGNITUDE = 0 The magnitude is prepared for display
PHASE = 1 The complex phase is prepared for display
REAL = 2 The real component is prepared for display
IMAG = 3 The imaginary component is prepared for display

enum class MappingMode: uint8

Enumerator for the intensity mapping mode

Enumerators
MANUAL = 0 dip::ImageDisplay::Limits are used as-is
MAXMIN = 1 The max and min values are taken as the display limits
PERCENTILE = 2 The 5% and 95% values are taken as the display limits
BASED = 3 0 should remain at the middle of the output range
LOGARITHMIC = 4 A logarithmic mapping is applied
MODULO = 5 The integer input values are mapped modulo the output range

Function documentation

ImageDisplay( dip::Image const& image, dip::ColorSpaceManager* colorSpaceManager = nullptr, dip::ExternalInterface* externalInterface = nullptr) explicit

The constructor takes an image with at least 1 dimension.

If colorSpaceManager is not nullptr, it points to the color space manager object to be used to convert the color image image to sRGB. If image is not color, or already is sRGB, the color space manager is not used. If no color space manager is given, image will be shown as is, no color space conversion is applied.

If externalInterface is not nullptr, then it is used to allocate the data segment for the output image.

Both colorSpaceManager and externalInterface, if given, must exist for as long as the ImageDisplay object exists.

dip::Image const& Input( ) const

Retrieves a reference to the input image.

dip::Image const& Slice( )

Retrieves a reference to the raw slice image.

This function also causes an update of the slice if the projection changed. The raw slice image contains the input data for the what is shown in dip::ImageDisplay::Output.

dip::Image const& Output( )

Retrieves a reference to the output image.

This function also causes an update of the output if any of the modes changed.

The output image data segment will be allocated using the external interface provided to the ImageDisplay constructor.

dip::Image::Pixel MapSinglePixel( dip::Image::Pixel const& input)

Puts a single pixel through the same mapping the image will go through to become dip::ImageDisplay::Output.

bool OutIsDirty( ) const

Returns true if the next call to dip::ImageDisplay::Output will yield a different result from the previous one. That is, the display needs to be redrawn.

bool SliceIsDirty( ) const

Returns true if the next call to dip::ImageDisplay::Output will yield a different slice

bool SizeIsDirty( ) const

Returns true if the next call to dip::ImageDisplay::Output will yield an output of a different size. That is, the slicing direction has changed, and this yields a change in sizes.

dip::Image::Pixel Pixel( dip::uint x, dip::uint y = 0)

Gets input image intensities at a given 2D point (automatically finds corresponding nD location). In case of a 1D dip::ImageDisplay::Output, y is ignored.

void SetDirection( dip::uint dim1, dip::uint dim2)

Sets the projection/slicing direction, as the two image dimensions to show along the x and y axis of the 2D display. If dim1==dim2, a 1D output is produced.

void SetCoordinates( dip::UnsignedArray coordinates)

Sets the current coordinates. This affects the slice displayed.

void SetTensorElements( dip::sint red, dip::sint green = -1, dip::sint blue = -1)

Sets the tensor element to be shown in each of the three output channels.

This function only has an effect for tensor images without a color space.

void SetProjectionMode( dip::ImageDisplay::ProjectionMode projectionMode)

Sets the projection mode. Has no effect if image dimensionality is equal to projection dimensionality.

void SetProjectionMode( dip::String const& projectionMode)

Sets the projection mode. Has no effect if image dimensionality is equal to projection dimensionality.

projectionMode value Meaning
"slice" the 1D/2D image shown is a slice through the nD image
"max" the 1D/2D image shown is the max projection of the nD image
"mean" the 1D/2D image shown is the mean projection of the nD image

For an image with complex samples, setting the projection mode to "max" forces the complex to real mapping mode to "magnitude".

For projection modes other than "slice", turns off global stretch mode.

void SetComplexMode( dip::ImageDisplay::ComplexMode complexMode)

Sets the complex to real mapping mode. Has no effect when projection mode is set to "max", or for non-complex images.

void SetComplexMode( dip::String const& complexMode)

Sets the complex to real mapping mode. Has no effect when projection mode is set to "max", or for non-complex images.

complexMode value Meaning
"magnitude" the intensity displayed is the magnitude of the complex values
"abs" synonym for "magnitude"
"phase" the intensity displayed is the phase of the complex values
"real" the intensity displayed is the real component of the complex values
"imag" the intensity displayed is the imaginary component of the complex values

void SetMappingMode( dip::ImageDisplay::MappingMode mappingMode)

Sets the intensity mapping mode. Has no effect for binary images.

void SetRange( dip::ImageDisplay::Limits range)

Sets the range of intensities to be mapped to the output range. Forces intensity mapping mode to linear. Has no effect for binary images.

void SetRange( dip::String const& range)

Sets the mapping mode and the range of intensities to be mapped to the output range. Has no effect for binary images.

range value Meaning
"unit" [0, 1]
"8bit" [0, 255]
"12bit" [0, 4095]
"16bit" [0, 65535]
"s8bit" [-128, 127]
"s12bit" [-2048, 2047]
"s16bit" [-32768, 32767]
"angle" [-π, π]
"orientation" [-π/2, π/2]
"lin" uses the full range of the image (or slice)
"percentile" uses the 5% to 95% range of the image
"base" uses the full range of the image (or slice), but keeps 0 at the middle of the output range
"log" the logarithm of the intensities are mapped to the full output range
"modulo" the integer input values are mapped modulo the output range
Additionally, the following aliases are defined:
"normal" same as "8bit"
"linear" same as "lin"
"all" same as "lin"
"based" same as "base"
"labels" same as "modulo"

void SetGlobalStretch( bool globalStretch)

Sets the global stretch mode. Has no effect on 2D images or when the projection mode is not "slice"

void SetGlobalStretch( dip::String const& globalStretch)

Sets the global stretch mode. Has no effect on 2D images or when the projection mode is not "slice"

globalStretch value Meaning
"yes" or "on" intensity stretching is computed using all values in the image
"no" or "off" intensity stretching is computed using only values visible in the current slice

std::pair<dip::uint, dip::uint> GetDirection( ) const

Get the projection/slicing direction. The two values returned are identical when output is 1D.

dip::UnsignedArray const& GetOrthogonal( ) const

Returns the array of dimensions orthogonal to those returned by dip::ImageDisplay::GetDirection. These are the dimensions not displayed.

dip::UnsignedArray const& GetCoordinates( ) const

Get the current coordinates.

dip::UnsignedArray const& GetSizes( ) const

Get the image sizes.

dip::uint Dimensionality( ) const

Get the image dimensionality.

dip::sint GetRedTensorElement( ) const

Get the tensor element to be shown in the red channel.

dip::sint GetGreenTensorElement( ) const

Get the tensor element to be shown in the green channel.

dip::sint GetBlueTensorElement( ) const

Get the tensor element to be shown in the blue channel.

dip::String GetProjectionMode( ) const

Get the current projection mode.

dip::String GetComplexMode( ) const

Get the current complex to real mapping mode.

dip::String GetMappingMode( ) const

Get the current intensity mapping mode.

dip::ImageDisplay::Limits GetRange( ) const

Get the current intensity range.

dip::ImageDisplay::Limits GetLimits( bool compute)

Gets the image intensity range (that selected with "lin") for the current slicing and complex mapping modes. If compute is true, it computes them if they’re not yet computed.

bool GetGlobalStretch( ) const

Get the current global stretch mode.