The display is a very important part of any image-processing package.
dip_image objects containing scalar or color images with 1 to 4
dimensions are displayed to MATLAB‘s figure windows. These windows are
completely cleared beforehand, meaning that images never share a window
with each other or with other graphical elements. This chapter describes
the possible interactions with figure windows, how to link variables
with them, and their placing on the desktop.
The figure windows described in this chapter are those created by the
function. This function is also used by default to automatically display
images when a when a MATLAB command does not end with a semicolon.
'DisplayToFigure' option in Other settings.
The alternative way to display images is with the
The figure windows created use the DIPviewer tool, which has better
image display capabilities (for example it can show tensor images),
but is not integrated equally well into MATLAB.
See the DIPviewer documentation
for more information on these figure windows.
'DisplayFunction' option (see Other settings)
controls which of these two commands is used to automatically display
The figure window menus
The display for an image contains four menus: “File”, “Sizes”, “Mappings” and “Actions”.
The first menu contains a “Save display…” option that saves the display to a file in PNG, TIFF, JPEG or EPS format. This allows you, for example, to save an image with labels, or to zoom into a portion of an image and only save that. It also contains a “Close” and a “Clear” item. On Windows machines, there is a “Copy display” option. It does the same as “Save”, but writes the image as a bitmap to the clipboard, so that it can be pasted into other applications.
“Sizes” contains options that call
diptruesize, which causes the image
to be displayed with an aspect ratio of 1, and various different zoom
factors (see Figure window support:
diptruesize). It also contains an
option that causes a the image to be stretched to fill the figure
window. The last option on this menu, “Default window size” resizes the
window to some pre-defined size (which is 256 by 256 pixels, but you can
change it using
dipsetpref, see Toolbox preferences:
dipgetpref and Other settings).
“Mappings” contains different ways of mapping the data for display.
These options correspond to calls to
dipmapping (see Figure window support:
The first section here contains stretching modes, which correspond to the
range parameter in
dipshow (see The
dipshow function). One of these options
is “Manual…”, which, through a dialog box, allows the user to select a
custom range. The second section, only available for grey-value images,
selects a colormap. The options in the first section will sometimes
change the selection of the colormap. If the image being displayed is
complex, this menu allows choosing the complex to real mapping performed
(magnitude, phase, real or imaginary part). For 3D and 4D images you can
select the orientation of the slices shown (X-Y, X-Z, Y-Z, X-T, Y-T,
Z-T), as well as decide whether the stretching mode selected is to be
computed on the whole volume (“Global stretch”) or only on the current
The “Actions” menu selects the actions that can be performed through the
mouse. The options “none”, “Pixel testing”, “Zoom”, “Looking glass” and
“Pan” (which correspond to the
dippan commands) are available to all image types. The 3D/4D image
display also contains an option to “Step through slices” (
See Using the mouse in figure windows for more information on these modes, and
Figure window support:
dipzoom, et al. for the associated commands. This menu also contains
a command to enable or disable the keyboard functionality in the window.
See Using the keyboard in figure windows for more information on this.
Finally, the “Actions” menu contains some more options:
“Link displays…” (
diplink) allows the user to link a display with other displays. When zooming, panning, stepping through the slices, or changing the orientation of the slicing, the images in the other displays will be kept in sync. This can be used to easily compare various images.
dipanimate) will step through all slices of a 3D/4D image in sequence. Calling this function from the command line allows the user to choose the speed of this animation.
“Isosurface plot…” (
dipisosurface) opens a new window, showing an isosurface plot of the image. This window contains some controls to modify the surface. You should be aware that it takes a while to generate an isosurface. It is recommended to smooth and down-sample an image before generating an isosurface plot. The isosurface plot is only available for 3D displays.
“View5d” (not yet ported over from DIPimage 2)
Programmatic updating of figure windows
dipshow function) displays an image to
a figure window. It accepts multiple optional arguments to specify
how the image is to be shown. Once displayed, it is possible to
further change these properties using the menus, as described above,
but also using additional commands:
dipmapping(Figure window support:
dipmapping) changes how pixel values are mapped to screen colors (stretching modes, color maps, slicing directions, etc.)
diptruesize(Figure window support:
diptruesize) changes the spatial scaling of the image (zoom factor).
Using the mouse in figure windows
As discussed above, the “Actions” menu allows selecting a mode for the
mouse to work in. Depending on the dimensionality and type of the image,
the modes are (the commands between brackets can also be used to turn
these modes on and off, see Figure window support:
dipzoom, et al.):
“None”: The mouse does nothing.
“Pixel testing” (
diptest): The mouse is used to examine pixel values and location. Depressing the left mouse button will cause the current cursor position to be displayed in the title bar, together with the grey-value (or color values) of the pixel at that location. It is possible to move the mouse while holding down the button. Depressing the right mouse button does the same thing, but the cursor position becomes the origin of the coordinate system. This allows for length measurements in images.
dipzoom): The mouse is used to zoom the image in and out. Clicking with the left mouse button zooms the image in with a factor 2, and clicking with the right one will zoom the image out with a factor 2. Double-clicking any mouse button will cause the image to be stretched to fill the figure window. Dragging a rectangle around an area of interest will cause it to be zoomed-in on.
The aspect ratio is set to 1:1 when zooming in or out, except after double-clicking. See Using the keyboard in figure windows to learn how to zoom using the keyboard.
“Looking glass” (
diplooking): The mouse is used to enlarge a part of the image.
dippan): The mouse is used to pan the image if it doesn’t fit in the window. Just press the left mouse button and move the mouse with the button down. It is also possible to pan using the keyboard (see Using the keyboard in figure windows).
“Step through slices” (
dipstep): The mouse is used to step through the slices of a 3D or 4D volume. It allows the user to click or drag the cursor over the image to go back and fourth through the slices that make up the volume. Moving the mouse down or to the right, while holding down the left button, displays higher slice numbers along the first hidden dimension. Moving the mouse up or to the left displays lower slice numbers. Alternatively, click with the left mouse button to go up, and with the right one to go down. If the displayed image is 4D, dragging the mouse with the right button down moves the display along the second hidden dimension. Using the keyboard in figure windows explains how to do step through slices with the keyboard.
Using the keyboard in figure windows
When the keyboard is enabled for a display window, it can be used to step through the slices of a 3D/4D image, zoom in and out, and pan the image. These functions are independent of the chosen mode for the mouse under the “Actions” menu.
The keys N and P step to the next and previous slice, respectively, of a 3D image. Additionally, you can type the number of a slice and press Enter to go to it. Note that slice numbers start with 0. In case of a 4D image, N and P step through the first hidden dimension (Z), whereas F and B step through the second hidden dimension (T).
The keys I and O are used to zoom in and out, respectively. The zoom factor is 2. When zoomed in, use the arrow keys to pan the image and get to the area of interest. Alternatively you can use the following keys instead: W for up, S for down, A for left, and D for right.
The Esc key disables the keyboard. This is useful under operating systems where displaying an image causes its window to gain keyboard focus. You would have to click on the command window to continue typing a new command. Instead, press Esc, which disables the keyboard for the window and causes your keystrokes to be send to the command window. To enable the keyboard again, use the menu item “Enable keyboard” under the “Actions” menu. With the command
Linking variables with figure windows
A variable name can be linked with the handle of a figure window, such
that any image stored in that variable will always be displayed in the
same window. This is done through the
dipfig function (see
Creating, linking and clearing figure windows:
dipclf). It is not possible to link a single
variable with more than one figure window, but it is possible to link
many variables to the same figure window. This system allows the user to
create a series of figure windows that will be reused, instead of having
new windows created all the time. These links do not, however, promise
that an image displayed is actually up-to-date. Changing the contents of
a variable does not change the contents of a figure window. By not
adding the semicolon at the end of commands, it is possible to
automatically update the figure windows (see Displaying
A special name
'other' is defined in
dipfig, that is a substitute
for all variables not explicitly linked to a figure window. It allows
the user to have a window for all possible images he can create.
'other' can be linked to a series of windows, which then will be used
Closing a window does not destroy the links that were made for it. Since variable names are linked to window numbers (handle), a window can be reopened to display the image with which it is linked.
Note that many toolbox functions that require a figure window handle as input also accept a variable name. Variable names linked with a figure window are considered aliases for a figure window handle.
Setting the position of figure windows
The position of a figure window can be changed by manipulating its
'Position' property, which is defined by an array with four values:
The coordinates for figure windows start at the bottom-left corner of
the screen, and are in screen pixels by default. This can be changed to
inches and other units:
See MATLAB Function Reference for more information on figure window properties. You can see a local copy of this page by typing from within MATLAB
dipfig function has an additional optional parameter, which can be
used to set the position of a figure window at the same time that it is
created. This parameter comes at the end of the parameter list, and is
the same array used for the
height values are those of the image that will fit in
the window, and the window itself is drawn around this area. These
values are always in screen pixels.
If an image is larger or smaller than the size of the window, the window
will be resized so that the image fits exactly. That is, unless the
'TrueSize' option is turned off (see Other settings),
in which case the window will not be
resized, and the image will be stretched to fit. To have your windows
fixed on the desktop, disable the
As with all other settings, the position of the figure windows cannot be
saved from one session to the next. Add the appropriate commands to your
dipinit.m files to have the same settings across
sessions (see Initialization file).