Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Interactive Modular Tool Workflow

Using the interactive modular tools typically involves the following steps.

StepDescriptionNotes
1Display the image to be processed (called the target image) in a figure window.Use the imshow function to display the target image, see Display the Target Image in a Figure Window.
2Create the modular tool, associating it with the target image.

You use the modular tool creation functions to create the tools — see Modular Interactive Tools for Building Custom Image Processing Apps for a list of available tools.

Most of the tools associate themselves with the image in the current axes, by default, but you can specify a specific image object, or a figure, axes, or uipanel object that contains an image. See Interactive Modular Tool Workflow.

Depending on how you designed your GUI, you might also want to specify the parent object of the modular tool itself. This is optional; by default, the tools either use the same parent as the target image or open in a separate figure window. See Specify the Parent of a Modular Tool for more information.

You might need to specify the position of the graphics objects in the GUI, including the modular tools. See Position Modular Tools in a GUI for more information.

3Set up interactivity between the tool and the target image. (Optional)

The modular tools all set up their interactive connections to the target image automatically. However, you can also specify custom connectivity using modular tool APIs. See Customize Modular Tool Interactivity for more information.

Display the Target Image in a 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 the 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 a 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 a 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: [537×358 uint8]
    CDataMapping: 'scaled'

  Use GET to 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: [537×358 uint8]
    CDataMapping: 'scaled'

  Use GET to show all properties

Specify the Parent of a 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.

Tools With Separate Creation Functions

Two of the tools, the Pixel Region tool and the Overview tool, have a separate creation function to provide this capability. Their primary creation functions, imoverview and impixelregion, open the tools in a separate figure window. To specify a different parent, you must use the imoverviewpanel and impixelregionpanel functions.

    Note   The Overview tool and the Pixel Region tool provide additional capabilities when created in their own figure windows. For example, both tools include zoom buttons that are not part of their uipanel versions.

Embed Pixel Region Tool in Existing Figure

This example shows the default behavior when you create the Pixel Region tool using the impixelregion function. The tool opens in a separate figure window, as shown in the following figure.

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

To embed the Pixel Region tool in the same window as the target image, you must specify the target image's parent figure as the parent of the Pixel Region tool when you create it.

The following example creates a figure and an axes object and then positions the objects in the figure to ensure their visibility. See Position Modular Tools in a GUI for more information. The example then creates the modular tools, specifying the figure containing the target image as the parent of the Pixel Region tool. Note that the example uses the impixelregionpanel function to create the tool.

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]);

The following figure shows the Pixel Region embedded in the same figure as the target image.

Position Modular Tools in a 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 the Parent of a 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.

Specify the Position with a Position Vector

To specify the position of a modular tool or other graphics object, set the value of the Position property of the object. As the value of this property, you specify a four-element position vector [left bottom width height], where left and bottom specify the distance from the lower left corner of the parent container object, such as a figure. The width and height specify the dimensions of the object.

When you use a position vector, you can specify the units of the values in the vector by setting the value of the Units property of the object. To allow better resizing behavior, use normalized units because they specify the relative position, not the exact location in pixels. See the reference pages for these graphics object for more details.

For example, when you first create an embedded Pixel Region tool in a figure, it appears to take over the entire figure because, by default, the position vector is set to [0 0 1 1], in normalized units. This position vector tells the tool to align itself with the bottom left corner of its parent and fill the entire object. To accommodate the image and the Pixel Information tool and Display Range tools, change the position of the Pixel Region tool in the lower half of the figure window, leaving room at the bottom for the Pixel Information and Display Range tools. Here is the position vector for the Pixel Region tool.

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

To accommodate the Pixel Region tool, reposition the target image so that it fits in the upper half of the figure window, using the following position vector. To reposition the image, you must specify the Position property of the axes object that contains it; image objects do not have a Position property.

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

Adding Navigation Aids to a GUI

    Note   The toolbox modular navigation tools are incompatible with standard MATLAB figure window navigation tools. When using these tools in a GUI, suppress the toolbar and menu bar in the figure windows to avoid conflicts between the tools.

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

  • Scroll Panel

  • Overview tool

  • Magnification box

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.

Understanding Scroll Panels

When you display an image in a scroll panel, it changes the object hierarchy of your displayed image. This diagram illustrates the typical object hierarchy for an image displayed in an axes object in a figure object.

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

The following figure shows this object hierarchy.

Object Hierarchy of Image Displayed in a Figure

When you call the imscrollpanel function to put the target image in a scrollable window, this object hierarchy changes. For example, this code adds a scroll panel to an image displayed in a figure window, specifying the parent of the scroll panel and the target image as arguments. The example suppresses the figure window toolbar and menu bar because they are not compatible with the scroll panel navigation tools.

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

The following figure shows the object hierarchy after the call to imscrollpanel. Note how imscrollpanel inserts a new object (shaded in gray) into the hierarchy between the figure object and the axes object containing the image. (To change the image data displayed in the scroll bar, use the replaceImage function in the imscrollpanel API.)

Object Hierarchy of Image Displayed in Scroll Panel

The following figure shows how these graphics objects appear in the scrollable image as it is displayed on the screen.

Components of a Scroll Panel

Was this topic helpful?