Arrows
R2026bDescription
An Arrows object labels one or more static arrows in a
Viewer object. The properties of the object control the appearance and
behavior of the static arrow 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.
Creation
You can create an Arrows object in these ways. For more information,
see Create Static Viewer-Based ROIs.
Use the
uiannotatefunction to create the ROI and display it in a specified viewer.Use the
images.ui.graphics.roi.static.Arrowsfunction described here. Display the ROI in a viewer by specifying theParentproperty value as the targetViewerobject during creation. Alternatively, display an ROI after you create it by adding the object to theAnnotationsproperty of aViewerobject.
Syntax
Description
a = images.ui.graphics.roi.static.Arrows creates an
Arrows object with default property values. Use
a to query and modify properties of the
Arrows object after you create it.
a = images.ui.graphics.roi.static.Arrows(
sets one or more properties using name-value arguments.PropertyName=Value)
Example:
a = images.ui.graphics.roi.static.Arrows(Position=[10 10 9 3; 20 20 3
9]) creates an Arrows object consisting of two arrow
shapes.
Properties
Shape and Position
Position of the ROI, specified as a numeric matrix with n rows, where n is the number of static arrows in the ROI. Each row specifies an arrow in one of these formats:
[x y u v mag]— The arrow is positioned at xy-coordinate (x,y), with the direction vector [uv], and magnitudemag. TheAlignmentproperty defines how each arrow displays relative to the position (x,y).[x y z u v w mag]— The arrow is positioned at xyz-coordinate (x,y,z), with the direction vector [uvw], and magnitudemag. TheAlignmentproperty defines how each arrow displays relative to the position (x,y).[x1 y1 x2 y2]— The tail of the arrow is at xy-coordinate (x1,y1). The head of the arrow is at xy-coordinate (x2,y2).[x1 y1 z1 x2 y2 z2]— The tail of the arrow is at xyz-coordinate (x1,y1,z1). The head of the arrow is at xyz-coordinate (x2,y2,z2).
The Arrows object stores the Position
property as an n-by-7 numeric matrix, where each row
represents an arrow in the form [x y z u v w mag]. If you
specify an arrow using 2-D xy-coordinates, the object sets
z to 1 and w to
0.
Arrow alignment relative to the position, specified as one of these strings.
"center"— The arrow stem is centered at the specified position."tail"— The tail of the arrow is located at the specified position."head"— The head of the arrow is located at the specified position."no-stem"— The head of the arrow is centered at the specified position, and no stem is displayed.
This property has no effect when you specify the
Position property as the coordinates of two points
in the format [x1 y1 x2 y2] or [x1 y1 z1 x2 y2
z2].
Geometric transformation that maps the intrinsic coordinate system to a world or map coordinate system, specified as one of the following.
2-D geometric transformation object:
affinetform2d,rigidtform2d,simtform2d, ortransltform2d3-D geometric transformation object:
affinetform3d,rigidtform3d,simtform3d,transltform3dMapping reference object:
MapCellsReference(Mapping Toolbox) orMapPostingsReference(Mapping Toolbox) (requires Mapping Toolbox™).Matrix of data type
doublerepresenting a 3-D affine geometric transformation. A valid 3-D affine transformation A has the form:
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 Triplet | Appearance | Default Use |
|---|---|---|
[0 0.5610 1] |
| This is the default color when creating a static ROI in dark mode. |
[0.8660 0.3290 0] |
| 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 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" |
|
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);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.
Transparency 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 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. |
Identifiers
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.
Examples
Display an image slice from a brain MRI in a Viewer object. The viewer, V, is the parent of the Image object created by imageshow.
data = load(fullfile(toolboxdir("images"),"imdata","BrainMRILabeled","images","vol_001.mat")); slice = data.vol(:,:,70); Img = imageshow(slice, DisplayRangeMode="data-range");
V = Img.Parent;
Create a position matrix in which each row defines one arrow in the format [x y u v mag], where (x, y) is the location, [u v] is the direction vector, and mag is the magnitude of the arrow. For example, in the first row, (157,158) marks a point on the tumor boundary, the direction [-1,0] points toward the tumor interior, and the magnitude is 50 pixels.
pos = [157 158 -1 0 50;
90 115 0 1 30 ];Create an Arrows object and display it in the viewer. A single object that contains all the annotations renders more efficiently than separate objects. To place the head of each arrow at the specified coordinates, specify the Alignment property as "head".
roi = images.ui.graphics.roi.static.Arrows(Position=pos,Parent=V,Alignment="head");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 three static arrows on the image, using the Position property to specify the position of the arrows in the form [x1 y1 x2 y2]. Each arrow points from the point (x1, y1) to the point (x2, y2).
pos = [570 110 440 200; ... 580 355 425 350; ... 140 350 235 355]; a = images.ui.graphics.roi.static.Arrows(Position=pos,Parent=v);
Overlay a color-coded arrow field on an image to visualize the displacement from nonrigid registration. The arrow directions show how pixels move, and color encodes displacement magnitude.
Read two images of the same hand in different poses.
fixed = imread("hands1.jpg"); moving = imread("hands2.jpg");
Convert the images from RGB to grayscale, and then perform histogram matching to correct for intensity differences between the images.
fixed = im2gray(fixed); moving = im2gray(moving); moving = imhistmatch(moving,fixed);
Calculate the displacement field needed to align the images.
moving = imhistmatch(moving, fixed);
[dispField, movingReg] = imregdemons(moving, fixed, [500 400 200], ...
AccumulatedFieldSmoothing=1.3, DisplayWaitbar=false);Compute the displacement magnitude at each pixel. Then, rescale the values to the range zero to one so the peak displacement maps to one pixel width.
dispMag = hypot(dispField(:,:,1), dispField(:,:,2)); mag = mat2gray(dispMag);
Build the position matrix for the arrows where each row is in [x y u v mag] format. First, create a grid of (x, y) coordinates matching the image pixels, then pair each location with its displacement vector and magnitude.
[X, Y] = ndgrid(1:size(movingReg,1), 1:size(movingReg,2)); xvec = dispField(:,:,1); yvec = dispField(:,:,2); pos = [Y(:) X(:) yvec(:) xvec(:) mag(:)];
Map displacement magnitude to color using the turbo colormap. Each arrow gets an RGB color based on its relative magnitude.
cmap = turbo; cmapIndex = im2uint8(mat2gray(dispMag(:))) + 1; color = cmap(cmapIndex,:);
Display the registered image and overlay the arrow field.
obj = imageshow(movingReg);
viewer = obj.Parent; roi = images.ui.graphics.roi.static.Arrows(Position=pos,Parent=viewer,Color=color);
This image shows a zoomed in view of one finger with a range of displacement values.
Load a brain MRI volume and display it in a Viewer object. The viewer is the parent of the object returned by volshow.
data = load(fullfile(toolboxdir("images"),"imdata","BrainMRILabeled","images","vol_001.mat")); obj = volshow(data.vol);
viewer = obj.Parent;
Build a position matrix defining arrows pointing to different locations in the volume. Each row specifies [x y z u v w mag], where (x,y,z) is the target point, (u,v,w) defines the direction vector of the arrow, and mag is the arrow length, in voxels.
pos = [132 180 66 0 -1 0 50;
55 162 25 1 0 0 50;
160 100 120 0 0 -1 50];Create an Arrows object and display it in the viewer. To place the head of each arrow at the target coordinates, specify the Alignment property value as "head".
roi = images.ui.graphics.roi.static.Arrows(Position=pos, Parent=viewer, Color="red", Alignment="head");
Version History
Introduced in R2026b
