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.
Classes
- struct Limits
- Intensity mapping limits
Enums
- enum class ProjectionMode: uint8{ SLICE, MAX, MEAN }
- Enumerator for the projection mode
- enum class ComplexMode: uint8{ MAGNITUDE, PHASE, REAL, IMAG }
- Enumerator for the complex mapping mode
- enum class MappingMode: uint8{ MANUAL, MAXMIN, PERCENTILE, BASED, LOGARITHMIC, MODULO }
- Enumerator for the intensity mapping mode
Functions
- auto Input() const -> dip::Image const&
- Retrieves a reference to the input image.
- auto Slice() -> dip::Image const&
- Retrieves a reference to the raw slice image.
- auto Output() -> dip::Image const&
- Retrieves a reference to the output 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::Outputwill yield a different result from the previous one. That is, the display needs to be redrawn. - auto SliceIsDirty() const -> bool
- Returns true if the next call to
dip::ImageDisplay::Outputwill yield a different slice - auto SizeIsDirty() const -> bool
- Returns true if the next call to
dip::ImageDisplay::Outputwill yield an output of a different size. That is, the slicing direction has changed, and this yields a change in sizes. - 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,yis 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.
- 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.
- 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. - 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.
- 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" - 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 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 GetCoordinates() const -> dip::UnsignedArray const&
- Get the current coordinates.
- auto GetSizes() const -> dip::UnsignedArray const&
- Get the image sizes.
- auto Dimensionality() const -> dip::uint
- Get the image dimensionality.
- auto GetRedTensorElement() const -> dip::sint
- Get the tensor element to be shown in the red channel.
- auto GetGreenTensorElement() const -> dip::sint
- Get the tensor element to be shown in the green channel.
- auto GetBlueTensorElement() const -> dip::sint
- Get the tensor element to be shown in the blue channel.
- auto GetProjectionMode() const -> dip::String
- Get the current projection mode.
- auto GetComplexMode() const -> dip::String
- Get the current complex to real mapping mode.
- auto GetMappingMode() const -> dip::String
- Get the current intensity mapping mode.
- auto GetRange() const -> dip::ImageDisplay::Limits
- Get the current intensity range.
- auto GetLimits(bool compute) -> dip::ImageDisplay::Limits
- Gets the image intensity range (that selected with
"lin") for the current slicing and complex mapping modes. Ifcomputeis true, it computes them if they’re not yet computed. - auto GetGlobalStretch() const -> bool
- Get the current global stretch mode.
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& 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.
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::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::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 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(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 |