Create Interactive Viewer-Based ROIs

R2026b

Interactive viewer-based ROIs enable you to draw, edit, and measure regions of interest on images and volumes displayed using imageshow and volshow. Interactive ROIs support dragging, resizing, event callbacks, and measurement labels. Use interactive viewer-based ROIs to manually annotate an image, build annotation workflows in apps, or respond to user interactions with ROI shapes.

You can create viewer-based ROI objects using these approaches.

  • Interactively from the viewer toolbar. In a Viewer object toolbar, select the Draw annotations icon Draw annotations icon, then select a shape to draw. Click and drag to draw the ROI. To export the ROI as an object, right-click the shape and select Export annotation to workspace.

  • Using the uidraw function, which enables you to interactively draw or programmatically specify an ROI in a single command. Use the uidraw function to create shapes that are not available in the viewer toolbar, or if you want to set the label or color before you draw the shape.

  • Programmatically using an object creation function, such as images.ui.graphics.roi.Circle. To display the ROI, add the object to the Annotations property of a Viewer object. Use this approach to more flexibly control the appearance and behavior of an ROI. For example, you can specify the face transparency or interactivity of ROIs within apps as you build them.

The table summarizes the options for creating each viewer-based ROI object.

DescriptionViewer Toolbar Supportuidraw SyntaxObject Creation Function

Line ROI that consists of a single line segment

Blue Line ROI drawn over the widest part of an object in an image.

2-D and 3-Duidraw(viewer,"line")images.ui.graphics.roi.Line

Point ROI

Blue Point ROI drawn near the center of an object in an image.

2-D and 3-Duidraw(viewer,"point")images.ui.graphics.roi.Point

Rectangle ROI

Blue Rectangle ROI encompassing an object in an image.

2-D onlyuidraw(viewer,"rectangle")images.ui.graphics.roi.Rectangle

Circle ROI

Blue Circle ROI drawn over a round object in an image.

2-D onlyuidraw(viewer,"circle")images.ui.graphics.roi.Circle

Polygon ROI that consists of a closed set of line segments

Blue Polygon ROI with 10 vertices approximating the boundary of an object in an image.

2-D onlyuidraw(viewer,"polygon")images.ui.graphics.roi.Polygon

Angle ROI

Blue Angle ROI measuring an angle in an image.

2-D onlyuidraw(viewer,"angle")images.ui.graphics.roi.Angle

Polyline ROI that consists of an open set of line segments

Blue Polyline ROI with 12 line segments approximating the boundary of an object in an image.

Noneuidraw(viewer,"polyline")images.ui.graphics.roi.Polyline

Freehand ROI that follows the path of the mouse

Freehand ROI tracing the edge of an object in an image.

Noneuidraw(viewer,"freehand")images.ui.graphics.roi.Freehand

Ellipse ROI

Blue Ellipse ROI drawn over a round object in an image.

Noneuidraw(viewer,"ellipse")images.ui.graphics.roi.Ellipse

Create Viewer-Based ROIs

Open Live Script

This example shows how to create viewer-based ROIs.

Create ROI from Viewer Toolbar

Read and display an image in a Viewer object.

Im = imageshow("pears.png");
viewer = Im.Parent;

From the toolbar in the top-right corner of the viewer, select the Draw annotations icon Control annotations icon and then select the Draw circle icon. Click and drag to draw the ROI. To export the ROI as an object, right-click the ROI and select Export annotation to workspace.

Pears image with a circle ROI around one object and the right-click context menu visible

Create ROI Using uidraw

The uidraw function enables you to interactively draw or programmatically specify ROIs.

Display the image in a new viewer. 

Im2 = imageshow("pears.png");
viewer2 = Im2.Parent;

Create a circle ROI by using the uidraw function, which enables an interactive drawing mode in the viewer. Click and drag in the viewer to draw the circle.

roi = uidraw(viewer2,"circle");

To create an ROI fully programmatically, specify the Position argument. For a circle, specify the position as a vector of the form [x y radius]. You can also customize the ROI color and label.

roi2 = uidraw(viewer2,"circle",Position=[450 204 70],Color="r",Label="Pear");

Pears image with a blue circle ROI with a numeric label around one pear, and a red circle ROI with the label Pear around another pear

Create ROI Using Object Creation Function

Object creation functions enable you to programmatically create ROIs with more customization options than the uidraw function.

Display the pears image in a new viewer.

Im3 = imageshow("pears.png");
viewer3 = Im3.Parent;

Create a circular ROI object. Use the Center and Radius properties to specify the position and size of the circle. To display the ROI, add it to the Annotations property of the Viewer object.

roi3 = images.ui.graphics.roi.Circle(Center=[445 204],Radius=75);
viewer3.Annotations = [viewer3.Annotations roi3];

Pears image with an orange circle ROI with a numeric label around a pear

Create Interactive Viewer-Based ROIs in Apps

To display interactive viewer-based ROIs in an app, create them in a Viewer object whose parent is a container component in your app. For example, you can parent the viewer to a figure, panel, or grid layout. You specify the code to create the viewer and ROIs using callback functions.

For example, you can configure an app to display an image and add a circular ROI within a panel. First, in the Design View of App Designer, drag a Panel component from the Component Library onto the canvas. Then, create a startupFcn callback by right-clicking the app node from the top of the Component Browser hierarchy and selecting Callbacks > Add StartupFcn callback. App Designer creates the function and places the cursor in the body of the function in Code View. Specify code to create a viewer, display the image, and create the ROI. You must specify the panel, app.Panel, as the parent of the viewer, and the viewer as the parent of the image and the ROI.

function startupFcn(app)
    viewer = viewer2d(Parent=app.Panel);
    imageshow("pears.png",Parent=viewer);
    circleROI = uidraw(viewer,"circle")
end

Click Run to save and run the app. The app opens and displays the image. Click and drag to draw the circle ROI on the image.

App Designer app window with a panel container in the top-left corner. The panel contains an image of pears with a circular ROI.

You can also create a viewer-based ROI by calling its object creation function, such as images.ui.graphics.roi.Circle. After you create an ROI, add it to the Annotations property of a Viewer object whose parent is a container component in your app.

See Also

Topics