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 Object	Current ROI Object
`imellipse`	Use `Ellipse` instead. With the previous set of ROIs, you used `imellipse` to draw a circular ROI. With the new ROIs, use `Circle`.
`imfreehand`	Use `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.
`imline`	Use `Line` instead.
`impoint`	Use `Point` instead.
`impoly`	Use `Polygon` instead. To create an open polygonal shape, use `Polyline`.
`imrect`	Use `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 Functions	Equivalent Object Functions
`addNewPositionCallback`	Use the `addListener` object function to specify the function you want executed when the ROI moves. For more information about using events, see ROI Events.
`createMask`	Use 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;`.
`getPositionConstraintFcn`	Use the `DrawingArea` property to specify position constraints.
`getVertices`	Retrieve the value of the `Vertices` property of the ROI. For example, `roi_vert = roi.Vertices;`.
`makeConstrainToRectFcn`	Use the `DrawingArea` property to specify position constraints.
`removeNewPositionCallback`	Use 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.
`resume`	Use `uiresume` instead.
`setClosed`	Assign a value to the ROI `Closed` property. For example, `roi.Closed = 'y'`.
`setColor`	Assign a value to the new ROI `Color` property. For example, `roi.Color = 'y'`.
`setConstrainedPosition`	Use the `DrawingArea` property to specify position constraints.
`setFixedAspectRatioMode`	Use `FixedAspectRatio` property of the new ROIs, setting the value to `true`.
`setPosition`	Assign a value to the new ROI `Position` property. The way to specify the position varies with each object. For example, `roi.Position = [50 50]`.
`setPositionConstraintFcn`	Use the `DrawingArea` property to specify position constraints.
`setResizable`	Use the `InteractionsAllowed` property, setting the value to `'translate'`.
`setString`	Assign a value to the new ROI `Label` property. For example, `roi.Label = 'My Label';`.
`setVerticesDraggable`	Use the `InteractionsAllowed` property, setting the value to `'translate'`.
`wait`	Use 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.

ROI Migration

ROI Object Migration

ROI Object Function Migration

ROI Events

Related Topics