Figure Windows
Contents
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 dipshow
function. This function is also used by default to automatically display images when a when a MATLAB command does not end with a semicolon. See the 'DisplayToFigure'
option in Other settings.
The alternative way to display images is with the viewslice
function. 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.
The 'DisplayFunction'
option (see Other settings) controls which of these two commands is used to automatically display images.
Programmatic updating of figure windows
The function dipshow
(The 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: diptest, 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. "Zoom" (
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. - "Pan" (
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 Windows, 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
dipsetpref('EnableKeyboard','off')
you disable the keyboard by default, and will have to use the above mentioned menu item to enable it. See Toolbox preferences: dipsetpref and dipgetpref and Other settings.
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: dipfig and 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 dip_
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 sequentially.
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: left
, bottom
, width
and height
.
set(handle,'Position',[left,bottom,width,heigth]);
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 centimeters
, inches
and other units:
set(handle,'Units','points');
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
web(fullfile(docroot,'matlab/ref/figure-properties.html'))
The 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 'Position'
property:
dipfig('a',[400,600,256,256]);
The width
and 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 'TrueSize'
option.
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 startup.m
or dipinit.m
files to have the same settings across sessions (see Initialization file).