Documentation Center

  • Trial Software
  • Product Updates

Creating the Modular Tools

Overview

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 a handle to 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.

Figure Window with Pixel Information Tool

Associating Modular Tools with a Particular Image

You can specify the target image of the modular tool when you create it by passing a handle to the target image as an argument to the modular tool creation function. You can also specify a handle to 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 handle to the target image. You could also have specified the handle of the figure, axes, or uipanel object containing the target image.

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

Note that the example retrieves handles to the uipanel objects created by the impixelinfo and imdisplayrange functions; both tools are uipanel objects. It can be helpful to get handles to the tools if you want to change their positioning. See Positioning the 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.

Figure Window with Pixel Information and Display Range Tools

Getting the Handle of the Target Image

The examples in the previous section use the optional imshow syntax that returns a handle to the image displayed, himage. When creating GUIs with the modular tools, having a handle to the target image can be useful. You can get the handle when you first display the image, using this optional imshow syntax. You can also get a handle to the target image using the imhandles function. The imhandles function returns all the image objects that are children of a specified figure, axes, uipanel, or image object.

For example, imshow returns a handle to the image in this syntax.

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

  152.0055

When you call the imhandles function, specifying a handle to the figure (or axes) containing the image, it returns a handle to the same image.

himage2 = imhandles(hfig)
himage2 =

  152.0055

Specifying 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.

Example: Embedding the Pixel Region Tool in an 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);

Target Image with Pixel Region Tool in Separate Window (Default)

To embed the Pixel Region tool in the same window as the target image, you must specify the handle of 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, getting handles to both objects. The example needs these handles to perform some repositioning of the objects in the figure to ensure their visibility. See Positioning the 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.

hfig = figure;
hax = axes('units','normalized','position',[0 .5 1 .5]);
himage = imshow('pout.tif')
hpixelinfopanel = impixelinfo(himage);
hdrangepanel = imdisplayrange(himage);
hpixreg = impixelregionpanel(hfig,himage);
set(hpixreg, 'Units','normalized','Position',[0 .08 1 .4]);

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

Target Image with Embedded Pixel Region Tool

Positioning the 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 standard Handle Graphics objects, such as uipanel objects, you can use properties of the objects to change their default positioning or other characteristics.

For example, in Specifying 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.

Specifying 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 page for the Handle 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])

Build a Pixel Information GUI

This example shows how to use the tools to create a simple GUI that provides information and pixels and features in an image. The GUI displays an image and includes the following modular pixel information tools:

  • Display Range tool

  • Distance tool

  • Pixel Information tool

  • Pixel Region tool panel

The example suppresses the figure window toolbar and menu bar because the standard figure zoom tools are not compatible with the toolbox modular navigation tools — see Adding Navigation Aids to a GUI.

function my_pixinfotool(im)
% Create figure, setting up properties
hfig = figure('Toolbar','none',...
              'Menubar', 'none',...
              'Name','My Pixel Info Tool',...
              'NumberTitle','off',...
              'IntegerHandle','off');

% Create axes and reposition the axes
% to accommodate the Pixel Region tool panel
hax = axes('Units','normalized',...
           'Position',[0 .5 1 .5]);

% Display image in the axes and get a handle to the image
himage = imshow(im);

% Add Distance tool, specifying axes as parent
hdist = imdistline(hax);

% Add Pixel Information tool, specifying image as parent
hpixinfo = impixelinfo(himage);

% Add Display Range tool, specifying image as parent
hdrange = imdisplayrange(himage);

% Add Pixel Region tool panel, specifying figure as parent
% and image as target
hpixreg = impixelregionpanel(hfig,himage);

% Reposition the Pixel Region tool to fit in the figure
% window, leaving room for the Pixel Information and
% Display Range tools.
set(hpixreg, 'units','normalized','position',[0 .08 1 .4])

To use the tool, pass it an image that is already in the MATLAB workspace.

pout = imread('pout.tif');
my_pixinfotool(pout);

The tool opens a figure window, displaying the image in the upper half, with the Distance tool overlaid on the image, and the Pixel Information tool, Display Range tool, and the Pixel Region tool panel in the lower half of the figure.

Custom Image Display Tool with Pixel Information

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 new objects (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

Example: Building a Navigation GUI for Large Images

If your work typically requires that you view large images, you might want to create a custom image display function that includes the modular navigation tools.

This example creates a tool that accepts an image as an argument and displays the image in a scroll panel with an Overview tool and a Magnification box.

    Note   Because the toolbox scrollable navigation is incompatible with standard MATLAB figure window navigation tools, the example suppresses the toolbar and menu bar in the figure window.

function my_large_image_display(im)

% Create a figure without toolbar and menubar.
hfig = figure('Toolbar','none',...
              'Menubar', 'none',...
              'Name','My Large Image Display Tool',...
              'NumberTitle','off',...
              'IntegerHandle','off');

% Display the image in a figure with imshow.
himage = imshow(im);

% Add the scroll panel.
hpanel = imscrollpanel(hfig,himage);

% Position the scroll panel to accommodate the other tools.
set(hpanel,'Units','normalized','Position',[0 .1 1 .9]);

% Add the Magnification box.
hMagBox = immagbox(hfig,himage);

% Position the Magnification box
pos = get(hMagBox,'Position');
set(hMagBox,'Position',[0 0 pos(3) pos(4)]);

% Add the Overview tool.
hovervw = imoverview(himage);

To use the tool, pass it a large image that is already in the MATLAB workspace.

big_image = imread('peppers.png');
my_large_image_display(big_image)

The tool opens a figure window, displaying the image in a scroll panel with the Overview tool and the Magnification Box tool.

Custom Image Display Tool with Navigation Aids

Was this topic helpful?