Display module

Image display

Contents

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 valueMeaning
"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 valueMeaning
"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 valueMeaning
"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 valueMeaning
"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.