Point

Point annotation

Since R2024a

Description

A Point object labels points in a Viewer object. The properties of the object control the appearance and behavior of the point 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 point on an imshow image display, use drawpoint instead.

Creation

You can create a Point object in these ways:

• Interactively draw a point in a Viewer object. From the viewer toolbar, select the draw annotations icon , then select the draw point icon . Click to place the point.

  To export the point to the workspace as a Point object, right-click the point 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.Point 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

p = images.ui.graphics.roi.Point

p = images.ui.graphics.roi.Point(Name=Value)

Description

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

p = images.ui.graphics.roi.Point(Name=Value) sets one or more writeable properties using name-value arguments.

Example: images.ui.graphics.roi.Point(Position=[35 3 1012]) creates a point annotation at the xyz-coordinates (35, 3, 1012).

Properties

Shape and Position

Position — Position of ROI

[0 0 0] (default) | 2-element numeric vector | 3-element numeric vector

Position of the ROI, specified as a 2-element numeric vector of the form [x y] or a 3-element numeric vector of the form [x y z]. If you specify this values as a 2-element vector, the object sets the z-coordinate of the point to 1. The object always stores this property value as a 3-element vector.

Color and Styling

Color — ROI color

RGB triplet | hexadecimal color code | color name | short color name

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 Triplet	Appearance	Default Use
[0 0.5610 1]		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]		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 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, 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"

Visible — ROI visibility

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

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.

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

Label — ROI label

string scalar | character vector | ""

ROI label, specified as a string scalar or character vector. By default, the label shows the position of the point with no units. 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

Interactions — Interactivity of ROI

"all" (default) | "none" | "translate" | "click"

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

Value	Description
"all"	You can fully interact with the ROI and translate (move) the ROI.
"none"	You cannot interact with the ROI. No drag points are visible.
"translate"	You can translate the ROI within the drawing area.
"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.

Identifiers

Parent — ROI parent

Viewer object

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 — Tag to associate with ROI

'' (default) | character vector | string scalar

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.

UserData — Data to associate with ROI

any MATLAB^® data

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

createMask

Create binary mask image from ROI

Examples

Create Point Annotation Object in 2-D Viewer

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 point ROI on the image, using the Position property to specify the position of the ROI.

position = [445 210];
p = images.ui.graphics.roi.Point(Position=position);

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

v.Annotations = [v.Annotations; p];

Create Point Annotation Object in 3-D Viewer

Create a new viewer window by displaying a 10-by-10-by-10 cube.

V = ones(10,10,10);
vol = volshow(V);

Get a handle to the viewer window that contains the volume.

viewer = vol.Parent;

Create a point annotation object with default property values.

point1 = images.ui.graphics.roi.Point

point1 = 
  Point with properties:

       Label: [0×0 string]
       Color: [0.8500 0.3250 0.0980]
    Position: [0 0 0]
         Tag: ""
    UserData: []

Create a point annotation with a custom position and label.

point2 = images.ui.graphics.roi.Point(Position=[1 10 10],Label="Point 2")

point2 = 
  Point with properties:

       Label: "Point 2"
       Color: [0.8500 0.3250 0.0980]
    Position: [1 10 10]
         Tag: ""
    UserData: []

Add the annotations to the viewer.

viewer.Annotations = [point1 point2];

To append spatial units to coordinate labels, update the SpatialUnits property of the viewer. By default, annotation labels do not display a unit.

viewer.SpatialUnits = "mm";

Tips

• The uidraw and images.ui.graphics.roi.Point 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 point on an imshow image display, use drawpoint instead.

• The Point object supports these forms of interactivity.

  Behavior	Interaction
  Add annotation	From the viewer toolbar, select the draw annotations icon , then select the draw point icon . Click to place the point.
  Move annotation	Drag the vertex of the annotation, not the label.
  Edit annotation label	Right-click the vertex of the annotation, not the label. 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 annotation	Right-click the vertex of the annotation, not the label. From the context menu, select Remove annotation. Select Remove all annotations to remove all annotations in the viewer.

• When placing annotations, consider zooming in or, for 3-D viewers, snapping to an orthogonal view for greater spatial accuracy. Zoom in using the scroll wheel, or by selecting the zoom icon from the viewer toolbar. Snap to an orthogonal view by clicking the orientation axes labels in the lower-left corner of the viewer.

Version History

Introduced in R2024a

R2026a: Support for 2-D viewers

You can now draw Point objects within 2-D viewers from the toolbar or by using the new uidraw function.

R2026a: New properties

The Point object has these new properties: Parent, Visible, and Interactions.

R2024b: Creation function renamed from images.ui.graphics3d.roi.Point

The function you use to create a new Point object has been renamed from images.ui.graphics3d.roi.Point to images.ui.graphics.roi.Point. There are no plans to remove support for references to the old function name.