Main Content


Set ROI object to new position

setConstrainedPosition is not recommended. For information about setting position constraints, see Compatibility Considerations.


setConstrainedPosition(h,pos) sets the ROI object h to a new position. The candidate position, pos, is subject to the position constraint function specified by setPositionConstraintFcn.

Input Arguments

collapse all

ROI object, specified as an imellipse, imline, impoint, impoly, or imrect object.

Candidate position of the ROI object, specified as a numeric array. The shape of the array depends on the type of ROI object, and is consistent with the form returned by the setPosition function.

ROI ObjectPosition
imellipse4-element vector of the form [xmin ymin width height], representing the new size and position of a bounding box around the ellipse. The new size of the bounding box is width-by-height pixels. The upper-left corner of the box is at the new (x,y) coordinate (xmin,ymin).
imline2-by-2 matrix of the form [x1 y1; x2 y2], representing the new position of the two endpoints of the line.
impoint1-by-2 vector of the form [x y].
impolyn-by-2 matrix. The two columns define the new x- and y-coordinates, respectively, of each of the n vertices.
imrect4-element vector of the form [xmin ymin width height]. The new size of the rectangle is width-by-height pixels. The upper-left corner of the rectangle is at the new (x,y) coordinate (xmin,ymin).

Version History

Introduced in R2008a

collapse all

R2018b: setConstrainedPosition is not recommended

Starting in R2018b, a new set of ROI objects replaces the existing set of ROI objects. The new objects provide more functional capabilities, such as face color transparency. The new classes also support events that you can use to respond to changes in your ROI such as moving or being clicked. Although there are no plans to remove the old ROI objects at this time, switch to the new ROIs to take advantage of the additional capabilities and flexibility. For more information on creating ROIs using the new ROI functions, see Create ROI Shapes.

With the existing ROIs, you use makeConstrainToRectFcn to create a function to specify the limits of the area in which you can draw or move an ROI. You then register this function with the ROI. When you use the setPosition object function, the ROI moves to wherever you specify, even if it is outside of the constrained limits. If you use setConstrainedPosition, the ROI honors the limits set by the constrained position function.

With the new ROIs, you use the DrawingArea property of the ROI to specify the area in which you can draw or move an ROI. When you set the location using the Position property, it does not honor limits set by the DrawingArea property.

Update Code

Update all instances of setConstrainedPosition.

Discouraged UsageRecommended Replacement

This example uses the makeConstrainToRectFcn function to create a 20-pixel border in which you cannot create or move an ROI. The example then tries to specify a location for the ROI that lies outside these limits. Using the setConstrainedPosition object function, the ROI does not honor locations specified outside the limits. Using the setPosition object function you can specify locations outside the limits.

h = impoint(gca,20,60);
% Make a function that constrains movement of the point
x = get(gca,'XLim');
y = get(gca,'YLim');
fcn = makeConstrainToRectFcn('impoint',x,y);;
% Apply the constraint function to the ROI.
% Try to specify a Position value outside the limits.
setConstrainedPosition(h,[1 51]);
% Note how ROI does not honor value outside of limits.

With the new ROIs, use the DrawingArea property to limit the area in which you can draw or move an ROI. This example creates a 20-pixel margin inside the image boundary. There is no way to make the ROI honor constraints when specifying a location in the Position property.

I = imread('cell.tif');
h = drawpoint(gca,'Position',[20 60])
[height width] = size(I); %Get image dimensions
h.DrawingArea = [20,20,(width-40),(height-40)];