Line
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 Viewer toolstrip. For
details, see Label Volume Display Using Point and Line Annotations.
Creation
Description
l = images.ui.graphics.roi.LineLine 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 Viewer object.
l = images.ui.graphics.roi.Line(Name=Value)images.ui.graphics.roi.Line(Position=[35 3 1012; 41 10 1080]) creates
a line annotation with endpoints at the specified xyz-locations.
Properties
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 from0toF. 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" |
|
"none" | Not applicable | Not applicable | Not applicable | No color |
This table lists the default color palettes for plots in the light and dark themes.
| Palette | Palette Colors |
|---|---|
Before R2025a: Most plots use these colors by 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);Before R2023b: Get the RGB triplets using RGB =
get(groot,"FactoryAxesColorOrder").
Before R2024a: Get the hexadecimal color codes using H =
compose("#%02X%02X%02X",round(RGB*255)).
Example:
Color="r"
Example:
Color="green"
Example: Color=[0 0.4470 0.7410]
Example: Color="#FF8800"
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"
Locations of the line annotation endpoints, specified as a 2-by-3 numeric matrix of
the form [x1 y1 z1; x2 y2 z2]. Each row specifies the position of one
line endpoint.
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.
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 a new viewer object 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 line annotation object with default properties.
line1 = images.ui.graphics.roi.Line
line1 =
Line with properties:
Label: [0×0 string]
Color: [0.8500 0.3250 0.0980]
Position: [2×3 single]
Tag: ""
UserData: []
Create a line annotation with a custom position and color.
line2 = images.ui.graphics.roi.Line(Position=[11 1 11; 1 11 11],Color="magenta")line2 =
Line with properties:
Label: [0×0 string]
Color: [1 0 1]
Position: [2×3 single]
Tag: ""
UserData: []
Add the annotations to the viewer. Because both endpoints of the default line, in orange, are at (0, 0, 0), the length of the line is 0.
viewer.Annotations = [line1 line2];
To append spatial units to length labels, update the SpatialUnits property of the viewer.
viewer.SpatialUnits = "mm";
Tips
The
Lineobject supports these forms of interactivity.Goal Action Add annotation From the
Viewertoolstrip, 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.
