uidraw

Interactively draw ROI in viewer window

Since R2026a

Syntax

roi = uidraw(viewer,shape)

roi = uidraw(viewer,shape,Name=Value)

Description

The uidraw function enables you to interactively draw ROI annotations in a Viewer object, which includes images displayed using the imageshow function and volumes displayed using volshow. You can specify the initial appearance of the ROI by using name-value arguments. After you create the ROI, you can use object properties to further customize the ROI annotation.

roi = uidraw(viewer,shape) creates an ROI object and enables you to interactively draw the ROI in the specified Viewer object.

roi = uidraw(viewer,shape,Name=Value) modifies the appearance and behavior of the drawing tool and ROI object using one or more name-value arguments. For example, you can specify the Position argument to place one or multiple ROIs in the viewer programmatically, without needing to draw them manually.

Examples

Interactively Draw Circle ROI in Viewer

Read an image into the workspace and display it.

viewer = viewer2d;
I = imageshow("coins.png",Parent=viewer);

Enable the interactive drawing tool for a circular ROI in the viewer window. Specify the viewer as the parent of the image object returned by imageshow. The function returns a Circle object.

d = uidraw(viewer,"circle");

To draw the circle ROI, click a point on the circumference of the circle, drag to the opposite point on the circumference, and release to finish drawing. The label displays the radius of the circle, in pixels. To resize the circle, drag a point on the circumference. To translate the circle without resizing, hold Ctrl while you drag a point on the circumference.

This screenshot shows the display after interactively drawing a circle to label one dime.

You can customize the appearance and behavior of the circle before you draw it by specifying name-value arguments. For example, specify a custom color and label, and then draw a circle around a nickel in the image.

n = uidraw(viewer,"circle",Color="red",Label="Nickel");

This screenshot shows the display after drawing the second circle.

Draw ROI Shapes Without Labels

Create a viewer and display an image in it.

viewer = viewer2d;
imageshow("peppers.png",Parent=viewer)

Enable the interactive drawing tool for a rectangular ROI in the viewer window. Specify the Label name-value argument as "" to display the rectangle without a label. To draw the rectangle, click and hold on the image to place a vertex, drag to draw the rectangle, and release to place the opposite vertex. The rectangle displays without a label.

roi = uidraw(viewer,"rectangle",Label="");

Draw ROIs with Real-World Spatial Units

Load a 3-D MRI image volume, vol, with 1-by-1-by-1 mm voxel spacing into the workspace. The MRI data is a modified subset of the BraTS data set [1].

dataDir = fullfile(toolboxdir("images"),"imdata","BrainMRILabeled");
load(fullfile(dataDir,"images","vol_001.mat"))

Create a viewer to display the volume. By default, ROI annotations display in voxel units with no label. To display a units label, specify the SpatialUnits property of the viewer.

viewer = viewer3d;
viewer.SpatialUnits = "mm";

Display the volume in the viewer as 2-D slice planes. Note that specifying the SpatialUnits property only changes the label units. If your volume has voxel spacing other than 1-by-1-by-1 mm, you must specify the Transformation argument of volshow to display the volume correctly and generate accurate measurements.

Volume = volshow(vol,Parent=viewer, ...
    RenderingStyle="SlicePlanes");

Add a line annotation to measure the tumor size using the uidraw function. To draw the line, first rotate the volume to view the transverse plane by clicking the Z axis indicator in the lower-left corner of the viewer. To facilitate accurate measurement, zoom in on the region containing the tumor. Click and hold the slice to place the first endpoint, drag to draw the line, and release to place the second endpoint.

line = uidraw(viewer,"line");

Zoom in to focus on the tumor region.

viewer.CameraZoom = 3;

Optionally, to reposition one endpoint, drag the endpoint, not the line or the label. To move the whole line, including both endpoints, hold Ctrl and drag one of the endpoints.

References

[1] Medical Segmentation Decathlon. "Brain Tumours." Tasks. Accessed May 10, 2018. http://medicaldecathlon.com/. The BraTS data set is provided by Medical Segmentation Decathlon under the CC-BY-SA 4.0 license. All warranties and representations are disclaimed. See the license for details. MathWorks® has modified the subset of data used in this example. This example uses the MRI data of one scan from the original data set, saved to a MAT file.

Programmatically Display Multiple Static ROIs

Display an image of colored, circular chips and display rectangles around the yellow chips.

Define positions for rectangles around the yellow chips. Each row defines the [x, y, width, height] for a rectangle.

chipPositions = [53 150 55 55;
                 275 310 55 55;
                 390 62 55 55;
                 405 138 55 55];

Create a viewer and display an image in it. Then, programmatically add the rectangles to the viewer. When you specify the Positions argument, the function skips interactive drawing and displays the specified ROIs. To display the ROIs as static objects, specify the Interactions name-value argument as "none". Disabling interactions can improve rendering speed, especially when you display many objects in a viewer. For example, use this approach to display hundreds of bounding boxes returned by an object detection algorithm.

viewer = viewer2d;
imageshow("coloredChips.png",Parent=viewer);

rois = uidraw(viewer, "rectangle", ...
    Position=chipPositions, ...
    Label="yellow", ...
    Interactions="none");

Input Arguments

viewer — Viewer to draw ROI in

Viewer object | child of Viewer object

Viewer to draw the ROI in, specified as a Viewer object or a child of a Viewer object. For example, you can specify a Viewer object you create by using the viewer2d or viewer3d function. Examples of child objects of a viewer include the Image object returned by imageshow and the Volume object returned by volshow.

This argument sets the Parent property of the output ROI object, and adds the ROI object to the Annotations property of the specified Viewer. If you specify a child of a Viewer, the function adds the ROI object to the Viewer object itself.

shape — Shape of ROI to draw

"line" | "point" | "circle" | ...

Shape of the ROI to draw, specified as one of the values in the table.

Value	Description
"line"	Create a Line object
"point"	Create a Point object
"polygon"	Create a Polygon object
"rectangle"	Create a Rectangle object
"circle"	Create a Circle object
"angle"	Create an Angle object
"freehand"	Create a Freehand object
"polyline"	Create a Polyline object
"ellipse"	Create an Ellipse object

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: uidraw(viewer,"circle",Color="red") creates a red Circle object.

Color — ROI color

RGB triplet | hexadecimal color code | color name | short color name | m-by-3 numeric matrix | string array

ROI color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. If you specify multiple ROIs by using the Position argument, you can specify one color to apply to all of the ROIs, or separate colors for each ROI. Specify colors for m ROIs as an m-by-3 array of RGB triplets or as an m-element string array containing hexadecimal color codes or color names.

Here are the default ROI colors used in 2-D and 3-D Viewer objects.

RGB Triplet	Appearance	When Used
[0 0.5610 1]		This is the default color when drawing an ROI in a 2-D Viewer.
[0.8660 0.3290 0]		This is the default color when drawing an ROI in a 3-D Viewer.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, this code gets the RGB triplets for the "gem" palette and converts them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Example: Color="r"

Example: Color=["green" "red" "blue"]

Example: Color=[0 0.4470 0.7410]

Crosshair — Display crosshair

"off" (default) | on/off logical value

Display a crosshair while you draw, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", the viewer displays a crosshair that can help guide you as you draw. When this value is "off", the crosshair is hidden.

Label — Label for ROI

string scalar | character vector | string array

Label for the ROI, specified as a string scalar, character vector, or string array. By default, the viewer displays a unitless measurement that depends on the specified shape, as outlined in the table. If the viewer has a nondefault value for the SpatialUnits property, such as "mm", the label includes the specified units.

To display a custom label, specify a string scalar or character vector. To display no label, specify "".

If you specify multiple ROIs by using the Position argument, you can specify a string scalar to label all of the ROIs, or a string array that contains one label per ROI.

Data Types: char | string

Position — Position for ROI

numeric vector | numeric matrix | cell array

Position for the ROI, specified as a numeric vector, numeric matrix, or cell array. When you specify Position, the function skips interactive drawing and creates the ROI programmatically. You can use the Position argument to specify multiple ROI annotations of the same shape.

You can specify each position using one of the options listed in this table. Values that omit z place the ROI in the default 2-D image plane, with z equal to 1.

Shape	Position
"line"	Single ROI: Specify a 2-by-2 or 2-by-3 numeric matrix of the form [x1 y1; x2 y2] or [x1 y1 z1; x2 y2 z2], respectively. Each row specifies one endpoint. Multiple ROIs, where m is the number of ROIs: Specify an m-by-4 or m-by-6 matrix, where each row specifies the endpoints of one line in the form [x1 y1 x2 y2] or [x1 y1 z1 x2 y2 z2], respectively. Specify an m-element cell array, where each element contains a 2-by-2 or 2-by-3 matrix specifying one line.
"point"	Single ROI: Specify a numeric vector of point coordinates of the form [x y] or [x y z]. Multiple ROIs, where m is the number of ROIs: Specify an m-by-2 or m-by-3 matrix, where each row specifies the coordinates of one point in the form [x y] or [x y z], respectively. Specify an m-element cell array, where each element contains a vector specifying one point.
"polygon"	Single ROI: Specify an n-by-2 or n-by-3 matrix, where each row specifies the [x y] or [x y z] coordinates, respectively, of the nth point in the polygon. Multiple ROIs, where m is the number of ROIs: Specify an m-element cell array where each element contains a matrix of [x y] or [x y z] coordinates for one polygon. Each polygon can contain a different number of points.
"rectangle"	Single ROI: Specify a numeric vector of the form [xmin ymin width height], where xmin and ymin specify the upper-left corner of the rectangle, and width and height specify the width and height. The rectangle always lies in the xy-plane, with z equal to 1. Multiple ROIs, where m is the number of ROIs: Specify an m-by-4 matrix where each row specifies one rectangle in the form [xmin ymin width height]. Specify an m-element cell array where each element contains a vector defining one rectangle.
"circle"	Single ROI: Specify a numeric vector of the form [x y radius] or [x y z radius], where x, y, and z specify the center coordinates, and radius specifies the radius. Multiple ROIs, where m is the number of ROIs: Specify an m-by-3 or m-by-4 matrix where each row specifies one circle in the form [x y radius] or [x y z radius], respectively. Specify an m-element cell array where each element contains a vector defining one circle.
"angle"	Single ROIs: Specify a 3-by-2 or 3-by-3 matrix of the form [x1 y1; x2 y2; x3 y3] or [x1 y1 z1; x2 y2 z2; x3 y3 z3], respectively. The second row defines the coordinates of the vertex, and the first and third rows define points on the rays that form the angle. Multiple ROIs, where m is the number of ROIs: Specify an m-by-6 or m-by-9 matrix, where each row defines one angle in the form [x1 y1 x2 y2 x3 y3] or [x1 y1 z1 x2 y2 z2 x3 y3 z3], respectively. The vertex of each angle is defined by x2, y2, and z2. Specify an m-element cell array, where each element contains a 3-by-2 or 3-by-3 matrix specifying one angle.
"freehand"	Single ROI: Specify an n-by-2 or n-by-3 matrix, where each row specifies the [x y] or [x y z] coordinates, respectively, of the nth point in the freehand shape. Multiple ROIs, where m is the number of ROIs: Specify an m-element cell array where each element contains a matrix of [x y] or [x y z] coordinates for one freehand shape. Each freehand shape can contain a different number of points.
"polyline"	Single ROI: Specify an n-by-2 or n-by-3 matrix, where each row specifies the [x y] or [x y z] coordinates, respectively, of the nth point in the polyline shape. Multiple ROIs, where m is the number of ROIs: Specify an m-element cell array where each element contains a matrix of [x y] or [x y z] coordinates for one polyline shape. Each polyline shape can contain a different number of points.
"ellipse"	Single ROI: Specify a numeric vector of the form [x y semix semiy] or [x y semix semiy theta] where x and y specifies the center coordinates, semix and semiy specify the horizontal and vertical semiaxes before rotation, and theta specifies the rotation angle. The rotation angle is the clockwise rotation about the center. If you omit theta, the function sets the rotation angle to 1. Multiple ROIs, where m is the number of ROIs: Specify an m-by-4 or m-by-5 matrix where each row specifies one ellipse in the form [x y semix semiy] or [x y semix semiy theta], respectively. Specify an m-element cell array where each element contains a vector defining one ellipse.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | cell

Wait — Behavior for blocking command line

"drawing" (default) | "accept" | "multiple" | "none

Behavior for blocking the command line during drawing, specified as one of the values in the table.

Value	Description
"drawing"	Block the command line during only drawing. The function resumes and returns the output object when you finish drawing.
"accept"	Block the command line until you accept the ROI by pressing Enter or selecting the accept icon in the viewer toolbar. Use this option when you want to draw and modify an ROI shape before the function resumes and returns the output object for that shape.
"multiple"	Block the command line until you accept one or more ROIs by pressing Enter or selecting the accept icon in the viewer toolbar. Use this option when you want to draw and modify multiple ROI shapes before the function resumes and returns the output shapes. If you draw multiple ROIs, the function returns an array of ROI objects.
"none"	Do not block the command line. The function returns an empty array of ROI objects. This option can be useful in custom apps when you want more flexible control. In this case, use listeners for the AnnotationAdded and AnnotationMoved events of the parent Viewer object to detect when annotations are added or edited.

Data Types: char | string

Output Arguments

roi — ROI

ROI object | array of ROI objects

ROI, returned as an ROI object or array of ROI objects of the type specified by shape. For example, if you specify shape as "circle", then the function creates a Circle object. The function returns an array of objects when you specify multiple ROIs by using the Position name-value argument or you specify the Wait name-value argument as "multiple" and draw multiple ROIs.

Version History

Introduced in R2026a