Rectangle

Rectangle annotation

Since R2026a

expand all in page

    Description

    A Rectangle object labels a rectangle in a Viewer object. The properties of the object control the appearance and behavior of the rectangle annotation.

    Viewer-based ROIs provide high-performance interactions with images and volumes you display in a Viewer object using imageshow and volshow, respectively. To draw a rectangle on an imshow image display, use drawrectangle instead.

    Blue Rectangle ROI encompassing an object in an image

    Creation

    You can create a Rectangle object in these ways:

    • Interactively draw a rectangle in a 2-D Viewer object. From the viewer toolbar, select the draw annotations icon draw annotations icon, then select the draw rectangle icon draw rectangle icon. To draw the rectangle, click to place one corner of the rectangle, drag to the opposite corner of the rectangle, and release. To export the rectangle to the workspace as a Rectangle object, right-click the edge of the rectangle and select Export annotation to workspace.

    • Use the uidraw function to interactively draw the ROI in a specified viewer and create the ROI object.

    • Use the images.ui.graphics.roi.Rectangle function described here. After you create the ROI, you can display it by adding the object to the Annotations property of a Viewer object.

    Syntax

    r = images.ui.graphics.roi.Rectangle
    r = images.ui.graphics.roi.Rectangle(Name=Value)

    Description

    r = images.ui.graphics.roi.Rectangle creates a Rectangle object with default property values. Use r to query and modify properties of the Rectangle object after you create it.

    r = images.ui.graphics.roi.Rectangle(Name=Value) sets one or more writable properties using name-value arguments.

    Example: images.ui.graphics.roi.Rectangle(Position=[128 64 200 100]) creates a rectangle annotation with a width of 200 pixels and height of 100 pixels. The upper-left corner of the rectangle is at the xy-coordinate (128, 64).

    example

    Properties

    expand all

    Shape and Position

    This property is read-only.

    Aspect ratio of the rectangle, represented as a positive number. The Rectangle object calculates this value as height/width, where height is the fourth element of Position and width is the third element of Position.

    Position of the ROI, specified as a 4-element numeric vector of the form [xmin ymin width height]. The values xmin and ymin specify the xy-coordinates of the upper-left corner of the rectangle. width and height specify the extent of the rectangle in two dimensions.

    Rotation angle around the center of the rectangle, specified as a numeric scalar. The angle is measured in degrees in a clockwise direction.

    The value of RotationAngle does not impact the values in the Position property. The Position property represents the initial position of the ROI, before rotation.

    This property is read-only.

    Area covered by the ROI, represented as a numeric scalar.

    This property is read-only.

    Perimeter of the ROI, represented as a numeric scalar.

    Color and Styling

    ROI color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name.

    These are the RGB triplets for the default colors used in 2-D and 3-D Viewer scenes.

    RGB TripletAppearanceDefault Use
    [0 0.5610 1]

    A rectangle colored medium-light blue

    		This is the default color when creating an ROI in a 2-D Viewer object from the toolbar or by using the uidraw function.
    [0.8660 0.3290 0]

    A rectangle colored orange

    		This is the default color when creating an ROI in a 3-D Viewer object from the toolbar or by using uidraw. This color is also the default when you create an ROI in any Viewer object by using an object constructor function such as images.ui.graphics.roi.Circle.

    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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

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

    PalettePalette Colors

    "gem" — Light theme default

    Before R2025a: Most plots use these colors by default.

    Sample of the "gem" color palette

    "glow" — Dark theme default

    Sample of the "glow" color palette

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

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

    Example: Color="r"

    Example: Color="green"

    Example: Color=[0 0.4470 0.7410]

    Example: Color="#00FFFF"

    Transparency of the ROI face, specified as a scalar in the range [0, 1]. When the value is 1, the ROI face is completely opaque. When the value is 0, the ROI face is completely transparent.

    ROI visibility, specified as "on" or "off", or as a numeric or logical 0 (false) or 1 (true). 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.

    ValueDescription
    "on"Display the ROI.
    "off"Hide the ROI without deleting it. You can still access the properties of an invisible ROI.

    ROI label, specified as a string scalar or character vector. By default, the label shows the width and height of the rectangle. If the parent Viewer has a nondefault value for the SpatialUnits property, such as "mm", then the label includes the specified units.

    To display a custom label, specify the label to display as a string scalar or character vector. To display no label, specify the Label value as "".

    Interactivity

    Interactivity of the ROI, specified as one of the values in this table.

    ValueDescription
    "all"You can fully interact with the ROI. Reshape the ROI by changing the position of individual vertices, translate (move) the entire ROI, or rotate the ROI.
    "none"You cannot interact with the ROI or access the context menu. No drag points are visible.
    "reshape"You can reshape the ROI by changing the position of individual vertices.
    "rotate"You can rotate the ROI.
    "translate"You can translate the entire ROI within the drawing area. The relative position of vertices is fixed, and you cannot reshape the ROI.
    "orthogonal"You can move and reshape the ROI. This is the default value.
    "click"You can click the ROI, but you cannot translate the ROI interactively. After you click the ROI, the parent Viewer broadcasts the AnnotationMoved event.

    ROI face supports interactions, 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.

    ValueDescription
    "on"The ROI face supports interactions. If Interactions is "all" or "translate", then you can interact with the ROI by clicking the face and dragging the ROI.
    "off"You cannot interact with the face of the ROI.

    Identifiers

    ROI parent, specified as a Viewer object. You can create a Viewer object for a 2-D image display or 3-D volume display by using the viewer2d or viewer3d function, respectively.

    Tag to associate with the ROI, specified as a character vector or string scalar. This property has no effect on the display, and the viewer does not use this property. You can use this property to track annotations for app building.

    Data to associate with the ROI, specified as any MATLAB data. For example, you can specify a scalar, vector, matrix, cell array, string, character array, table, or structure. This property has no effect on the display, and the viewer does not use this property. You can use this property to append metadata to the ROI for app building.

    Object Functions

    createMaskCreate binary mask image from ROI

    Examples

    collapse all

    Open Live Script

    Display an image in a Viewer object. The viewer v is the parent of the image object created by imageshow.

    img = imageshow("pears.png");
v = img.Parent;

    Create a rectangular ROI on the image, using the Position property to specify the position of the ROI in the form [xmin ymin width height].

    position = [370 122 153 162];
r = images.ui.graphics.roi.Rectangle(Position=position);

    Display the ROI by adding it to the Annotations property of the Viewer object.

    v.Annotations = [v.Annotations; r];

    Pears image with rectangle ROI with numeric label around one object

    Tips

    • The uidraw and images.ui.graphics.roi.Rectangle functions create ROIs to display in a Viewer object. Viewer-based ROIs provide high-performance interactions with images and volumes you display in a Viewer object using imageshow and volshow, respectively. To draw a rectangle on an imshow image display, use drawrectangle instead.

    • The ROI supports this interactivity, including keyboard shortcuts.

      BehaviorInteraction
      Add annotation

      From the viewer toolbar, select the draw annotations icon draw annotations icon, then select the draw rectangle icon draw rectangle icon. To draw the rectangle, click to place one corner of the rectangle, drag to the opposite corner of the rectangle, and release. Hold Shift while you drag to draw a square.

      Resize (reshape) annotation

      Drag a vertex on the corner of the rectangle to resize it in both dimensions, or drag a vertex on an edge of the rectangle to resize it in only one dimension. To preserve the aspect ratio while resizing, hold Shift while you drag.

      Move annotationHold Ctrl and drag the ROI.
      Edit annotation labelRight-click the ROI. From the context menu, select Edit label. When the label text highlights, type new text for the label. To finish editing, click outside the label.
      Remove annotationRight-click the ROI and choose Remove annotation from the context menu. Select Remove all annotations to remove all annotations in the viewer.

    Version History

    Introduced in R2026a

    See Also

    | | |

    Topics