Documentation

Display Target Image in Figure Window

As the foundation for any image processing GUI you create, use imshow to display the target image (or images) in a MATLAB^® figure window. (You can also use the MATLAB image or imagesc functions.) Once the image is displayed in the figure, you can associate any of the modular tools with the image displayed in the figure.

This example uses imshow to display an image in a figure window.

himage = imshow('pout.tif');

Because some of the modular tools add themselves to the figure window containing the image, make sure that the Image Processing Toolbox™ ImshowBorder preference is set to 'loose', if you are using the imshow function. (This is the default setting.) By including a border, you ensure that the modular tools are not displayed over the image in the figure.

Associate Modular Tools with Target Image

To associate a modular tool with a target image displayed in a MATLAB figure window, you must create the tool using the appropriate tool creation function. You specify the target image as an argument to the tool creation function. The function creates the tool and automatically sets up the interactivity connection between the tool and the target image.

By default, most of the modular tool creation functions support a no-argument syntax that uses the image in the current figure as the target image. If the current figure contains multiple images, the tools associate themselves with the first image in the figure object's children (the last image created). impixelinfo, impixelinfoval and imdisplayrange can work with multiple images in a figure.

For example, to use the Pixel Information tool with a target image, display the image in a figure window, using imshow, and then call the impixelinfo function to create the tool. In this example, the image in the current figure is the target image.

imshow('pout.tif');
impixelinfo

The following figure shows the target image in a figure with the Pixel Information tool in the lower left corner of the window. The Pixel Information tool automatically sets up a connection to the target image: when you move the pointer over the image, the tool displays the x- and y-coordinates and value of the pixel under the pointer.

Associate Modular Tools with Particular Target Image

You specify the target image of the modular tool when you create it by passing the image as an argument to the modular tool creation function. You can also specify a figure, axes, or uipanel object that contains the target image.

Continuing the example in the previous section, you might want to add the Display Range tool to the figure window that already contains the Pixel Information tool. To do this, call the imdisplayrange function, specifying the target image. You could also have specified the figure, axes, or uipanel object containing the target image.

imageobj = imshow('pout.tif');
pixelinfopanelobj = impixelinfo(imageobj);
drangepanelobj = imdisplayrange(imageobj);

Note that the tool creation functions return the uipanel objects created by the impixelinfo and imdisplayrange functions. You can use these objects if you want to change the positioning of the tools. See Position Modular Tools in GUI for more information.

The following figure shows the target image in a figure with the Pixel Information tool in the lower left corner and the Display Range tool in the lower right corner of the window. The Display Range tool automatically sets up a connection to the target image: when you move the pointer over the image (or images) in the figure, the Display Range tool shows the display range of the image.

Get Handle to Target Image

This example shows several ways to get the handle to the image displayed in a figure window, referred to as the target image. This can be useful when creating apps with the modular interactive tools.

Get the handle when you initially display the image in a figure window using the imshow syntax that returns a handle.

hfig = figure;
himage = imshow('moon.tif')

himage = 
  Image with properties:

           CData: [537x358 uint8]
    CDataMapping: 'scaled'

  Show all properties

Get the handle after you have displayed the image in a figure window using the imhandles function. You must specify a handle to the figure window as a parameter.

himage2 = imhandles(hfig)

himage2 = 
  Image with properties:

           CData: [537x358 uint8]
    CDataMapping: 'scaled'

  Show all properties

Specify Parent of Modular Tool

When you create a modular tool, in addition to specifying the target image, you can optionally specify the object that you want to be the parent of the tool. By specifying the parent, you determine where the tool appears on your screen. Using this syntax of the modular tool creation functions, you can add the tool to the figure window containing the target image, open the tool in a separate figure window, or create some other combination.

Specifying the parent is optional; the modular tools all have a default behavior. Some of the smaller tools, such as the Pixel Information tool, use the parent of the target image as their parent, inserting themselves in the same figure window as the target image. Other modular tools, such as the Pixel Region tool or the Overview tool, open in separate figures of their own.

himage = imshow('pout.tif')
hpixelinfopanel = impixelinfo(himage);
hdrangepanel = imdisplayrange(himage);
hpixreg = impixelregion(himage);

fig = figure;
ax = axes('units','normalized','position',[0 .5 1 .5]);
img = imshow('pout.tif')
pixelinfopanelobj = impixelinfo(img);
drangepanelobj = imdisplayrange(img);
pixregionobj = impixelregionpanel(fig,img);
set(pixregionobj, 'Units','normalized','Position',[0 .08 1 .4]);

Position Modular Tools in GUI

When you create the modular tools, they have default positioning behavior. For example, the impixelinfo function creates the tool as a uipanel object that is the full width of the figure window, positioned in the lower left corner of the target image figure window.

Because the modular tools are constructed from graphics objects, such as uipanel objects, you can use properties of the objects to change their default positioning or other characteristics.

For example, in Specify Parent of Modular Tool, when the Pixel Region tool was embedded in the same figure window as the target image, the example had to reposition both the image object and the Pixel Region tool uipanel object to make them both visible in the figure window.

set(hpixreg, 'Units','normalized','Position',[0 .08 1 .4])

set(hax,'Units','normalized','Position',[0 0.5 1 0.5])

Adding Navigation Aids to GUI

The toolbox includes several modular tools that you can use to add navigation aids to a GUI application:

The Scroll Panel is the primary navigation tool; it is a prerequisite for the other navigation tools. When you display an image in a Scroll Panel, the tool displays only a portion of the image, if it is too big to fit into the figure window. When only a portion of the image is visible, the Scroll Panel adds horizontal and vertical scroll bars, to enable viewing of the parts of the image that are not currently visible.

Once you create a Scroll Panel, you can optionally add the other modular navigation tools: the Overview tool and the Magnification tool. The Overview tool displays a view of the entire image, scaled to fit, with a rectangle superimposed over it that indicates the part of the image that is currently visible in the scroll panel. The Magnification Box displays the current magnification of the image and can be used to change the magnification.

The following sections provide more details.

hfig = figure;
himage = imshow('concordaerial.png');

hfig = figure('Toolbar','none',...
              'Menubar', 'none');
himage = imshow('concordaerial.png');
hpanel = imscrollpanel(hfig,himage);