Line

Line annotation

Since R2024a

Description

A Line object labels lines in a volume display. The properties of the object control the appearance and behavior of the line annotation. You can create a Line object interactively from the Viewer3D toolstrip. For details, see Label Volume Display Using Point and Line Annotations.

Creation

Syntax

l = images.ui.graphics3d.roi.Line

l = images.ui.graphics3d.roi.Line(Name=Value)

Description

l = images.ui.graphics3d.roi.Line creates a Line object with default property values. Use l to query and modify properties of the Line object after you create the object. To display the annotation, add l to the Annotations property of a Viewer3D object.

l = images.ui.graphics3d.roi.Line(Name=Value) sets properties of the object using one or more name-value arguments. For example, images.ui.graphics3d.roi.Line(Position=[35 3 1012; 41 10 1080]) creates a line annotation with endpoints at the specified xyz-locations.

Properties

Color — Color of line annotation

[0.85 0.325 0.098] (default) | RGB triplet | hexadecimal color code | color name | short color name

Color of the line annotation, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. The default color is orange, defined by the RGB triplet [0.85 0.325 0.098].

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 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"
"none"	Not applicable	Not applicable	Not applicable	No color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^® uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

Example: Color="r"

Example: Color="green"

Example: Color=[0 0.4470 0.7410]

Example: Color="#FF8800"

Label — Label for line annotation

string scalar | character vector

Label for the line annotation, specified as a string scalar or character vector. By default, the viewer displays the 3-D distance between the line endpoints with no units. If you add the Line object to a viewer that has a nondefault value for the ScaleBarUnits property, such as "mm", 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 "".

Example: Label="Width"

Position — Locations of line annotation endpoints

[0 0 0; 0 0 0] (default) | 2-by-3 numeric matrix

Locations of the line annotation endpoints, specified as a 2-by-3 numeric matrix of the form [x1 y 1 z1; x2 y2 z2]. Each row specifies the position of one line endpoint.

Tag — Tag for line annotation

"" (default) | string scalar

Tag for the line annotation, specified as a string scalar. This property has no effect on the volume display, and the viewer does not use this property. You can use this property to track annotations for app building.

UserData — User data associated with line annotation

any MATLAB data

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

Examples

Create Line Annotation Object

Create a line annotation object with default properties.

line1 = images.ui.graphics3d.roi.Line

line1 = 
  Line with properties:

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

Create a viewer and add the line annotation. By default, the endpoints of the line are both located at (0, 0, 0), so the length of the line is 0.

viewer = viewer3d(Annotations=line1);

Create a line annotation with a custom position and color.

line2 = images.ui.graphics3d.roi.Line(Position=[0 1 0; 0 1 1],Color="magenta")

line2 = 
  Line with properties:

       Color: [1 0 1]
       Label: [0×0 string]
    Position: [2×3 single]
         Tag: ""
    UserData: []

Add the second line to the viewer by using dot notation.

viewer.Annotations = [viewer.Annotations line2];

To append spatial units to length labels, update the SpatialUnits property of the viewer.

viewer.SpatialUnits = "mm";

Tips

• The Line object supports these forms of interactivity.

  Goal	Action
  Add annotation	From the Viewer3D toolstrip, pause on the point annotation icon , and then select the line icon . To place the first endpoint, click the surface of an object in the viewer. Then, drag to draw the line, and release the button to place the second endpoint.
  Move annotation	To reposition one endpoint, drag the endpoint. You can reposition the endpoint anywhere on the surface of an object in the viewer. To reposition the whole line, including both endpoints, hold Ctrl while you drag one of the endpoints.
  Edit annotation label	Right-click an endpoint of the annotation, not the label or the line. 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 an endpoint of the annotation, not the label or the line. From the context menu, select Remove annotation to remove the selected annotation. Select Remove all annotations to remove all annotations in the viewer.

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

Version History

Introduced in R2024a