Main Content

Line

Line annotation

Since R2024a

expand all in page

    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

    Syntax

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

    Description

    l = images.ui.graphics.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 Viewer object.

    example

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

    Properties

    expand all

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

    "none"Not applicableNot applicableNot applicableNo color

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

    RGB TripletHexadecimal Color CodeAppearance
    [0 0.4470 0.7410]"#0072BD"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    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 y 1 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

    collapse all

    Open Live Script

    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 Line object supports these forms of interactivity.

      GoalAction
      Add annotation

      From the Viewer toolstrip, pause on the point annotation icon Point annotation icon, and then select the line icon Line annotation object. 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 labelRight-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 annotationRight-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 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

    expand all

    See Also

    | | |

    Topics