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 image or imagesc functions.

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 using the imshow function, then make sure that the Image Processing Toolbox™ ImshowBorder preference is set to "loose" (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 panel 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.

Some tools can work with multiple images in a figure. These are impixelinfo, impixelinfoval, and imdisplayrange.

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, imoverview and impixelregion, open the tools in a separate figure window. To specify a different parent, you must use the imoverviewpanel and impixelregionpanel functions. For an example, see Create Pixel Region Tool.
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 panel versions.

Position Tools

Each tool has default positioning behavior. For example, the impixelinfo function creates the tool as a panel 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 panel 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 vector [left bottom width height]. The values of left and bottom specify the distance from the lower left corner of the parent container object, such as a figure. The values of width and height specify the dimensions of the object.

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

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.

Note

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