Main Content

ROI Migration

Starting in R2018b, a new set of ROI objects replaced the previous set of ROI objects. The new objects provide better performance and more functional capabilities, such as face color transparency. With the new objects, you can also receive notification of interactions with the object, such as clicks or movement, using events. 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 the new ROIs, see Create ROI Shapes.

ROI Object Migration

If your code uses one of the previous ROI objects, replace this with a call to the corresponding new ROI object. Because the new ROIs offer shapes that weren't supported previously, in some cases, you have several ROIs to choose from. Two ROIs in the new system have no corresponding ROI in the previous system: Crosshair and Cuboid.

Previous ROI ObjectCurrent ROI Object
imellipseUse Ellipse instead. With the previous set of ROIs, you used imellipse to draw a circular ROI. With the new ROIs, use Circle.
imfreehandUse Freehand instead. You can also use AssistedFreehand to create a hand-drawn ROI that "assists" your drawing by automatically following the contours of edges in the underlying image.
imlineUse Line instead.
impointUse Point instead.
impolyUse Polygon instead. To create an open polygonal shape, use Polyline.
imrectUse Rectangle instead.

ROI Object Function Migration

The previous set of ROIs used object functions to customize many aspects of ROI appearance and functioning. In many cases, the new ROIs replace these object functions with object properties. Instead of calling an object function, you get the value of a property or set the value of a property. For example, instead of using getColor to get the color of the ROI, access the value of the Color property of the new ROI object. For detailed information about how to migrate code to the new ROI system, see the Compatibility Considerations section of the object function reference pages associated with the previous ROI objects.

Previous ROI Object FunctionsEquivalent Object Functions
addNewPositionCallbackUse the addListener object function to specify the function you want executed when the ROI moves. For more information about using events, see ROI Events.
createMaskUse the equivalent createMask object function with the new ROIs.
getColor

Retrieve the value of the Color property of the ROI. For example,

roi_color = roi.Color;.

getPosition

Retrieve the value of the Position property of the ROI. For example,

roi_pos = roi.Position;.

getPositionConstraintFcnUse the DrawingArea property to specify position constraints.
getVertices

Retrieve the value of the Vertices property of the ROI. For example,

roi_vert = roi.Vertices;.

makeConstrainToRectFcnUse the DrawingArea property to specify position constraints.
removeNewPositionCallbackUse the addListener object function to specify the function to be called with the ROI moves. To remove this callback function, delete the object returned by the addListener object function.
resumeUse uiresume instead.
setClosedAssign a value to the ROI Closed property. For example, roi.Closed = 'y'.
setColorAssign a value to the new ROI Color property. For example, roi.Color = 'y'.
setConstrainedPositionUse the DrawingArea property to specify position constraints.
setFixedAspectRatioModeUse FixedAspectRatio property of the new ROIs, setting the value to true.
setPositionAssign a value to the new ROI Position property. The way to specify the position varies with each object. For example, roi.Position = [50 50].
setPositionConstraintFcnUse the DrawingArea property to specify position constraints.
setResizableUse the InteractionsAllowed property, setting the value to 'translate'.
setStringAssign a value to the new ROI Label property. For example, roi.Label = 'My Label';.
setVerticesDraggableUse the InteractionsAllowed property, setting the value to 'translate'.
waitUse the equivalent wait with the new ROI objects. Note that the new wait function does not support a return value containing position information.

ROI Events

With the previous ROIs, you could use the addNewPositionCallback object function to receive notification when the ROI moves. You specify the object and the function that you want executed when the event occurs: id = addNewPositionCallback(h,fcn).

With the new ROIs, you use the addListener object function to receive notification when the ROI moves. You specify the object, the name of the event you want to receive notification, and the name of the function you want executed when the event occurs: el = addlistener(roi,'ROIMoving',mycallbackfcn). With the new ROIs, you must specify the name of the event because you can receive notification of many other events, such as when the ROI is clicked.

To see an example, see the Compatibility Considerations section on the addNewPositionCallback reference page.

Related Topics