Using the interactive modular tools typically involves the following steps.
|1||Display the image to be processed (called the target image) in a figure window.||Use the |
|2||Create 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.
|3||Set 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.
As the foundation for any image processing GUI you create, use
display the target image (or images) in a MATLAB® figure window.
(You can also use the MATLAB
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™
is set to
'loose', if you are using the
(This is the default setting.) By including a border, you ensure that
the modular tools are not displayed over the image in the figure.
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).
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
and then call the
impixelinfo function to create
the tool. In this example, the image in the current figure is the
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.
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
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
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.
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
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.
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,
open the tools in a separate figure window. To specify a different
parent, you must use the
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.
This example shows the default behavior when you create the
Pixel Region tool using the
The tool opens in a separate figure window, as shown in the following
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
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.
When you create the modular tools, they have default positioning
behavior. For example, the
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
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.
To specify the position of a modular tool or other graphics
object, set the value of the
of the object. As the value of this property, you specify a four-element
[left bottom width height], where
the distance from the lower left corner of the parent container object,
such as a figure. The
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
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
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
Position property of the axes object that contains
it; image objects do not have a
set(hax,'Units','normalized','Position',[0 0.5 1 0.5])
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:
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 — Adding a scroll panel to an image display changes the relationship of the graphics objects used in the display. This section provides some essential background.
Build App for Navigating Large Images — This section shows how to add a scroll panel to an image display.
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
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
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
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