Circles

R2026b

Static circle annotation

Since R2026b

expand all in page

    Description

    A Circles object labels one or more static circles in a Viewer object. The properties of the object control the appearance and behavior of the static circle annotations.

    Static ROIs provide high-performance annotations for images and volumes you display in a Viewer object using imageshow and volshow, respectively. Use static ROIs to draw large numbers of ROIs on a viewer. For best performance, specify all the static ROIs together in a single function call instead of creating multiple objects. Static ROIs are more efficient than customizable viewer-based ROIs because they support fewer properties for styling, labeling, and interactions. For a comparison of static viewer-based ROIs with other ROIs, see Choose Approach to Annotate ROIs in Images.

    Blue circles overlaid on a grayscale image of coins

    Creation

    You can create a Circles object in these ways. For more information, see Create Static Viewer-Based ROIs.

    • Use the uiannotate function to create the ROI and display it in a specified viewer.

    • Use the images.ui.graphics.roi.static.Circles function described here. Display the ROI in a viewer by specifying the Parent property value as the target Viewer object during creation. Alternatively, display an ROI after you create it by adding the object to the Annotations property of a Viewer object.

    Syntax

    c = images.ui.graphics.roi.static.Circles
    c = images.ui.graphics.roi.static.Circles(PropertyName=Value)

    Description

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

    c = images.ui.graphics.roi.static.Circles(PropertyName=Value) sets one or more properties using name-value arguments.

    Example: c = images.ui.graphics.roi.static.Circles(Position=[10 20 8 5; 30 30 8 5]) creates a Circles object consisting of two circle shapes.

    example

    Properties

    expand all

    Shape and Position

    Position of the ROI, specified as an n-by-3 numeric matrix or an n-by-4 numeric matrix, where n is the number of static circles in the ROI. Each row specifies a circle in one of these formats:

    • [x y r] — The center of the circle is at xy-coordinate (x, y), and the circle has radius r. The object sets the z-coordinate of the center to 1.

    • [x y z r] — The center of the circle is at xyz-coordinate (x, y, z), and the circle has radius r.

    The Circles object stores the Position property as an n-by-4 numeric matrix, where each row represents a circle in the form [x y z r].

    Center coordinate of the ROI, specified as an n-by-2 numeric matrix or an n-by-3 numeric matrix, where n is the number of static circles in the ROI. Each row specifies the center coordinate of a circle in one of these formats:

    • [x y] — The center of the circle is at xy-coordinate (x, y), and the object sets the z-coordinate of the center to 1.

    • [x y z] — The center of the circle is at xyz-coordinate (x, y, z).

    The Circles object stores the Center property as an n-by-3 numeric matrix. Each row represents the center coordinate of a circle in the form [x y z].

    You cannot specify this property when you create the object. After you create the object, you can set this property using dot notation.

    Radius of each circle, specified as an n-element numeric vector.

    You cannot specify this property when you create the object. After you create the object, you can set this property using dot notation.

    Geometric transformation that maps the intrinsic coordinate system to a world or map coordinate system, specified as one of the following.

    By default, Transformation is a 4-by-4 identity matrix.

    Color and Styling

    ROI color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. You can also specify multiple colors as an n-by-3 numeric matrix where each row is an RGB triplet. If you specify a single color, then all shapes in the ROI display with the same color. If you specify multiple colors, then n must be equal to the number of shapes in the ROI.

    This table shows the default colors for static ROIs.

    RGB TripletAppearanceDefault Use
    [0 0.5610 1]

    A rectangle colored medium-light blue

    		This is the default color when creating a static ROI in dark mode.
    [0.8660 0.3290 0]

    A rectangle colored orange

    		This is the default color when creating a static ROI in light mode.

    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" specifies that all shapes of the ROI are colored red.

    Example: Color=[0 0.447 0.741] specifies that all shapes of the ROI have a custom color define by the RGB triplet [0 0.447 0.741].

    Example: Color=parula(5) specifies that each of five shapes within an ROI have a different color from the parula colormap.

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

    Opacity 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.

    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 is the parent of the image object created by imageshow.

    I = imread("circlesBrightDark.png");
img = imageshow(I);

    viewer = img.Parent;

    Define the positions for the circle annotations. Get the center coordinates and radii for bright circles in the image, and combine them into one position matrix with each row in the [x y radius] format.

    [centers,radii] = imfindcircles(I,[30 65],ObjectPolarity="bright");
pos = [centers radii];

    Create a Circles object and display it in the viewer, using the Position property to specify the position data. A single object that contains all the circles renders more efficiently than separate annotations objects.

    c = images.ui.graphics.roi.static.Circles(Position=pos,Parent=viewer);

    Version History

    Introduced in R2026b

    See Also

    | | | | |

    Topics