Creating Your Own Modular Tools

On this page…
Overview Example: Creating an Angle Measurement Tool

Overview

Because the toolbox uses an open architecture for the modular interactive tools, you can extend the toolbox by creating your own modular interactive tools, using standard Handle Graphics concepts and techniques. To help you create tools that integrate well with the existing modular interactive tools, the toolbox includes many utility functions that perform commonly needed tasks.

The utility functions can help check the input arguments to your tool, add callback functions to a callback list or remove them from a list, and align figure windows in relation to a fixed window. The toolbox also provides a set of functions that you can use to define a region-of-interest of various shapes, including points, lines, rectangles, ellipses, polygons, and freehand shapes — see Example: Creating an Angle Measurement Tool for more information.

The following table lists these utility functions in alphabetical order. See the function's reference page for more detailed information.

Utility Function	Description
getimagemodel	Retrieve image model objects from image handles
getrangefromclass	Get default display range of image, based on its class
imagemodel	Access to properties of an image relevant to its display
imattributes	Return information about image attributes
imellipse	Create draggable, resizable ellipse
imfreehand	Create draggable freehand region
imgca	Get handle to current axes containing an image
imgcf	Get handle to most recent current figure containing an image
imgetfile	Display Open Image dialog box
imhandles	Get all image handles
imline	Create draggable, resizable line
impoint	Create draggable point
impoly	Create draggable, resizable polygon
imputfile	Display Save Image dialog box
imrect	Create draggable, resizable rectangle
iptaddcallback	Add function handle to a callback list
iptcheckconn	Check validity of connectivity argument
iptcheckhandle	Check validity of image handle argument
iptcheckinput	Check validity of input argument
iptcheckmap	Check validity of colormap argument
iptchecknargin	Check number of input arguments
iptcheckstrs	Check validity of string argument
iptgetapi	Get application programmer interface (API) for a handle
iptGetPointerBehavior	Retrieve pointer behavior from HG object
ipticondir	Return names of directories containing IPT and MATLAB icons
iptnum2ordinal	Convert positive integer to ordinal string
iptPointerManager	Install mouse pointer manager in figure
iptremovecallback	Delete function handle from callback list
iptSetPointerBehavior	Store pointer behavior in HG object
iptwindowalign	Align figure windows

Back to Top

Example: Creating an Angle Measurement Tool

The toolbox includes a set of functions that you can use to enable users of your image processing GUI to define a region-of-interest (ROI) on the target image. The functions implement drawing of various shapes of ROI, such as rectangles, ellipses, and polygons, and returning information about the coordinates that define the ROI. These ROI objects support methods that you can use to control aspects of its appearance and behavior.

To illustrate how to use these ROI tools, this example creates a simple angle measurement tool This custom tool uses impoly to create a two-segment polyline on an image and displays the angle created by the two line segments in a title in the figure. Users of the tool can move the polyline anywhere on the image and view the angle formed by the two line segments.

function my_angle_measurement_tool(im)
% Create figure, setting up properties
figure('Name','My Angle Measurement Tool',...
      'NumberTitle','off',...
      'IntegerHandle','off');
% Display image in the axes
imshow(im)
% Get size of image.
m = size(im,1);
n = size(im,2);
% Get center point of image for initial positioning.
midy = ceil(m/2);
midx = ceil(n/2);
% Position first point vertically above the middle.
firstx = midx;
firsty = midy - ceil(m/4);
lastx = midx + ceil(n/4);
lasty = midy;
% Create a two-segment right-angle polyline centered in the image.
h = impoly(gca,[firstx,firsty;midx,midy;lastx,lasty],'Closed',false);
api = iptgetapi(h);
initial_position = api.getPosition()
% Display initial position
updateAngle(initial_position)
% set up callback to update angle in title.
api.addNewPositionCallback(@updateAngle);
fcn = makeConstrainToRectFcn('impoly',get(gca,'XLim'),get(gca,'YLim'));
api.setPositionConstraintFcn(fcn);
%

% Callback function that calculates the angle and updates the title.
% Function receives an array containing the current x,y position of
% the three vertices.
function updateAngle(p)
% Create two vectors from the vertices.
% v1 = [x1 - x2, y1 - y2]
% v2 = [x3 - x2, Y3 - y2]
v1 = [p(1,1)-p(2,1), p(1,2)-p(2,2)];
v2 = [p(3,1)-p(2,1), p(3,2)-p(2,2)];
% Find the angle.
theta = acos(dot(v1,v2)/(norm(v1)*norm(v2)));
% Convert it to degrees.
angle_degrees = (theta * (180/pi));
% Display the angle in the title of the figure.
title(sprintf('(%1.0f) degrees',angle_degrees))

To use the angle measurement tool, pass it an image.

I = imread('gantrycrane.png');
my_angle_measurement_tool(I);

The tool opens a figure window, displaying the image with the angle measure tool centered over the image in a right angle. Move the pointer over any of the vertices of the tool to measure any angle in the image. In the following figure, the tool is measuring an angle in the image. Note the size of the angle displayed in the title of the figure.

Custom Angle Measurement Tool

Back to Top

Customizing Modular Tool Interactivity

Spatial Transformations

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS