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 Build Custom Image Processing Apps Using Modular Interactive Tools 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 Parent of 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 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
imshow to display the target image (or images) in a
MATLAB® figure window. (You can also use the MATLAB
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
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
ImshowBorder preference is set to
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.
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).
imdisplayrange can work with multiple images in a
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.
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
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
You can use these objects if you want to change the positioning of the tools. See
Position Modular Tools in GUI for more
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: [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
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,
impixelregion, open the
tools in a separate figure window. To specify a different parent, you must use
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
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 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.
When you create the modular tools, they have default positioning behavior. For
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.
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
width height], where
bottom specify the distance from the lower left corner of
the parent container object, such as a figure. The
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
set(hax,'Units','normalized','Position',[0 0.5 1 0.5])
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.
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
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
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