Interactive Tool Workflow
Using the interactive tools typically involves the following steps.
Display Target Image in Figure Window
Display the image to be processed (called the target image)
in a MATLAB® figure window. The
imshow function is recommended
because it optimizes figure, axes, and image object properties for image display,
but you can also use the
Some of the tools add themselves to the figure window containing the image.
Prevent the tools from displaying over the image by including a border. If you are
imshow function, then make sure that the Image Processing Toolbox™
ImshowBorder preference is set to
(this is the default setting).
Create the Tool
After you display an image in a figure window, create one or more tools using the corresponding tool creation functions. For a list of available tools, see Interactive Image Viewing and Processing Tools. The functions create the tools and automatically set up the interactivity connection between the tool and the target image.
Associate Tool with Target Image
When you create a tool, you can specify the target image or you can let the tool pick a suitable target image.
To specify the target image, provide a handle to the target image as an input argument to the tool creation function. The handle can be a specific image object, or a figure, axes, or uipanel object that contains an image.
To let the tool pick the target image, call the tool creation function with no input arguments. By default, the tool uses the image in the current figure as the target image. If the current figure contains multiple images, then the tool associates with the first image in the figure object's children (the last image created). Note that not all tools offer a no-argument syntax.
Specify Parent of Tool
When you create a tool, 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 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. When you do not specify the parent, the tools use default behavior.
Some of the smaller tools, such as the Display Range tool and 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 tools, such as the Adjust Contrast tool and Choose Colormap tool, open in separate figures of their own.
Two tools, the Overview tool and Pixel Region tool, have different creation functions for specifying the parent figure. Their primary creation functions,
impixelregion, open the tools in a separate figure window. To specify a different parent, you must use the
impixelregionpanelfunctions. For an example, see Create Pixel Region Tool.
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.
Each tool has 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 tools are constructed from graphics objects, such as uipanel objects,
you can change their default positioning or other characteristics by setting
properties of the objects. To specify the position of a tool or other graphics
object, set the
Position property as a four-element position
[left bottom width height]. The values of
bottom specify the distance from
the lower left corner of the parent container object, such as a figure. The values
height specify the dimensions of
When you specify 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 of the tool, not the exact location in pixels.
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
[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])
For an example, see Create Pixel Region Tool.
Add Navigation Aids
The toolbox includes tools that you can use to add navigation aids to a GUI application.
The Scroll Panel is the primary navigation tool and 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 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.
Adding a scroll panel to an image display changes the relationship of the graphics objects used in the display. For more information, see Add Scroll Panel to Figure.
The toolbox 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.
Customize Tool Interactivity
When you create a tool and associate it with a target image, the tool automatically makes the necessary connections between the target image and the tool.
Some tools have a one-way connection to the target image. These tools get updated when you interact with the target image, but you cannot use the tool to modify the target image. For example, the Pixel Information tool receives information about the location and value of the pixel currently under the pointer.
Other tools have a two-way connection to the target image. These tools get updated when you interact with the target image, and you can update the target image by interacting with the tools. For example, the Overview tool sets up a two-way connection to the target image. For this tool, if you change the visible portion of the target image by scrolling, panning, or by changing the magnification, then the Overview tool changes the size and location of the detail rectangle to match the portion of the image that is now visible. Conversely, if you move the detail window in the Overview tool, then the tool updates the visible portion of the target image in the scroll panel.
The tools accomplish this interactivity by using callback properties of the
graphics objects. For example, the figure object supports a
WindowButtonMotionFcn callback that executes whenever the
mouse button is depressed. You can customize the connectivity of a tool by using the
application programmer interface (API) associated with the tool to set up callbacks
to get notification of events. For more information, see Create Callbacks for Graphics Objects and Overview Events and Listeners. For an
example, see Build Image Comparison Tool.
For example, the Magnification box supports a single API function:
setMagnification. You can use this API function to set the
magnification value displayed in the Magnification box. The Magnification box
automatically notifies the scroll panel to change the magnification of the image
based on the value. The scroll panel also supports an extensive set of API
functions. To get information about these APIs, see the reference page for each
- Create Pixel Region Tool
- Build App for Navigating Large Images
- Build App to Display Pixel Information
- Build Image Comparison Tool