Display module
#include <diplib/display.h>

Image display

Reference
- Modules
- Classes
- Enums
- Functions
- Variables

Modules

module DIPviewer: Interactive image display.

Classes

struct dip::ImageDisplay::Limits: Intensity mapping limits.
class dip::ImageDisplay: Encapsulates state of an image in a display window, and provides the functionality for converting the image to a form suitable for display.

Enums

enum class ProjectionMode: unsigned char { SLICE, MAX, MEAN }: Enumerator for the projection mode.
enum class ComplexMode: unsigned char { MAGNITUDE, PHASE, REAL, IMAG }: Enumerator for the complex mapping mode.
enum class MappingMode: unsigned char { MANUAL, MAXMIN, PERCENTILE, BASED, LOGARITHMIC, MODULO }: Enumerator for the intensity mapping mode.

Functions

ImageDisplay(Image const& image, ColorSpaceManager* colorSpaceManager = nullptr, ExternalInterface* externalInterface = nullptr) explicit: The constructor takes an image with at least 1 dimension.
auto Input() const -> Image const &: Retrieves a reference to the input image.
auto Slice() -> Image const &: Retrieves a reference to the raw slice image.
auto Output() -> Image const &: Retrieves a reference to the output image.
auto MapSinglePixel(Image::Pixel const& input) -> Image::Pixel: Puts a single pixel through the same mapping the image will go through to become Output.
auto OutIsDirty() const -> bool: Returns true if the next call to Output will 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 Output will yield a different slice.
auto SizeIsDirty() const -> bool: Returns true if the next call to Output will 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) -> Image::Pixel: Gets input image intensities at a given 2D point (automatically finds corresponding nD location). In case of a 1D 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(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(ProjectionMode projectionMode): Sets the projection mode. Has no effect if image dimensionality is equal to projection dimensionality.
void SetProjectionMode(String const& projectionMode): Sets the projection mode. Has no effect if image dimensionality is equal to projection dimensionality.
void SetComplexMode(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(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(MappingMode mappingMode): Sets the intensity mapping mode. Has no effect for binary images.
void SetRange(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(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(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 -> UnsignedArray const &: Returns the array of dimensions orthogonal to those returned by GetDirection. These are the dimensions not displayed.
auto GetCoordinates() const -> UnsignedArray const &: Get the current coordinates.
auto GetSizes() const -> UnsignedArray const &: Get the image sizes.
auto Dimensionality() const -> dip::uint: Get the image dimensionality.
auto GetRedTensorElement() -> dip::sint: Get the tensor element to be shown in the red channel.
auto GetGreenTensorElement() -> dip::sint: Get the tensor element to be shown in the green channel.
auto GetBlueTensorElement() -> dip::sint: Get the tensor element to be shown in the blue channel.
auto GetProjectionMode() const -> String: Get the current projection mode.
auto GetComplexMode() const -> String: Get the current complex to real mapping mode.
auto GetMappingMode() const -> String: Get the current intensity mapping mode.
auto GetRange() const -> Limits: Get the current intensity range.
auto GetLimits(bool compute) -> 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 GetGlobalStretch() const -> bool: Get the current global stretch mode.
void ApplyColorMap(Image const& in, Image& out, String const& colorMap = "grey"): Applies a color map to an image prepared for display using dip::ImageDisplay.
void Overlay(Image const& in, Image const& overlay, Image& out, Image::Pixel const& color = { 255, 0, 0 }): Adds a colored overlay to the image in, yielding an RGB image.
void MarkLabelEdges(Image const& labels, Image& out, dip::uint factor = 2): Upscales a labeled image and outlines each region with the background label.

Variables

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

Enum documentation

enum class ProjectionMode: unsigned char

Enumerator for the projection mode.

Enumerators
SLICE	A slice is prepared for display.
MAX	The max projection is prepared for display.
MEAN	The mean projection is prepared for display.

enum class ComplexMode: unsigned char

Enumerator for the complex mapping mode.

Enumerators
MAGNITUDE	The magnitude is prepared for display.
PHASE	The complex phase is prepared for display.
REAL	The real component is prepared for display.
IMAG	The imaginary component is prepared for display.

enum class MappingMode: unsigned char

Enumerator for the intensity mapping mode.

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

Function documentation

ImageDisplay(Image const& image, ColorSpaceManager* colorSpaceManager = nullptr, 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.

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

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

void ApplyColorMap(Image const& in, Image& out, String const& colorMap = "grey")

Applies a color map to an image prepared for display using dip::ImageDisplay.

in is a scalar, 8-bit unsigned image. out will be an image of the same size and type but with three tensor components, and in the "sRGB" color space.

colorMap can currently be one of the following color maps:

"grey": Each grey level maps to an RGB value that represents the same grey level.
"saturation": Each grey level maps to an RGB value that represents the same grey level, except pixels with a value 0 and 255, which are colored blue and red respectively. This can be used to show which pixels were likely saturated during acquisition.
"linear": A blue-magenta-yellow highly saturated, perceptually linear color map.
"diverging": A blue-grey-red diverging, perceptually linear color map, where the middle value maps to a neutral grey-value, high values map to increasingly bright reds, and low values map to increasingly bright blues. This is meant to be used in combination with the "base" range mode of dip::ImageDisplay.
"cyclic": A magenta-yellow-green-blue cyclic, perceptually linear color map, which allows four orientations or angles to be visualised. Use in combination with the "angle" or "orientation" range mode of dip::ImageDisplay.
"label": For labeled images, each grey value gets a color that can easily be distinguished from that of nearby grey values. 16 different colors are used. The 0 grey value is considered background and colored black. Use with the "modulo" range mode of dip::ImageDisplay.

For more information regarding the range modes of dip::ImageDisplay, see dip::ImageDisplay::SetRange.

The "linear", "diverging" and "cyclic" are by Peter Kovesi.

void Overlay(Image const& in, Image const& overlay, Image& out, Image::Pixel const& color = { 255, 0, 0 })

Adds a colored overlay to the image in, yielding an RGB image.

in must be either scalar (grey-value image) or RGB. overlay can be binary or integer.

In the case of a binary overlay image, the pixels selected by it will be assigned the value color, which defaults to red. If color is a scalar value, it will be interpreted as an intensity value, producing a grey overlay. In this latter case, if in was a scalar image, then the output will be scalar as well.

In the case of an integer overlay image, dip::ApplyColorMap with the "label" option will be used to create a label image overlay. color will be ignored.

void MarkLabelEdges(Image const& labels, Image& out, dip::uint factor = 2)

Upscales a labeled image and outlines each region with the background label.

out will be a labeled image like labels, but factor times as large along each dimension. In the upscaled image, the pixels that form the border of each region are set to 0, the background label.