File Exchange

image thumbnail

Annotate

version 1.2.1.1 (12.4 KB) by Todd Baxter
Create an annotation that is pinned to the axes of a graph.

24 Downloads

Updated 21 Jun 2020

View License

Usage:

OBJ = Annotate(AX, TYPE, X, Y)
OBJ = Annotate(AX, TYPE, X, Y, 'PropertyName', Value, ...)

Inputs:

AX <1x1 axes handle>
- Handle to axes where annotation is to be pinned

TYPE <character array>
- Type of annotation to create
- 'line', 'arrow', 'doublearrow', 'textarrow',
'rectangle', 'ellipse', or 'textbox'

X <1x2 or 2x1 numeric vector>
- Annotation X position in axes data coordinates
- Must lie within the visible axes limits
- For annotation types 'line', 'arrow', 'doublearrow', and 'textarrow', X(1)
specifies the tail end of the arrow and X(2) specifies the tip of the arrow head
- For annotation types 'rectangle', 'ellipse', and 'textbox', X(1)
specifies the left edge/extent and X(2) specifies the right edge/extent

Y <1x2 or 2x1 numeric vector>
- Annotation Y position in axes data coordinates
- Must lie within the visible axes limits
- For annotation types 'line', 'arrow', 'doublearrow', and 'textarrow', Y(1)
specifies the tail end of the arrow and Y(2) specifies the tip of the arrow head
- For annotation types 'rectangle', 'ellipse', and 'textbox', Y(1)
specifies the bottom edge/extent and Y(2) specifies the top edge/extent

Optional property name/value pairs can be specified to control the
appearance of the annotation object. See 'annotation' documentation
and property pages for each annotation type for more details.

Outputs:

OBJ <1x1 Annotate object handle>
- The Annotate object provides the following properties for
interaction with the annotation object.
* 'Position' allows for setting/getting the annotation object
position in axes data coordinates defined as [X(1),X(2),Y(1),Y(2)].
Note, rounding errors can occur.
* 'Primitive' is the handle to the annotation object, which allows
for further customization of its appearance.

Description:

Annotate creates an annotation object of type TYPE which is automatically
pinned to the axes with handle AX at the position specified by vectors
X and Y in axes data coordinates.

A UIContextMenu is attached to the annotation object which replicates the
standard annotation customizations (color, line width, line style, etc.),
normally accessed through edit plot mode, without having to enter edit plot
mode. The UIContextMenu also provides move/resize and delete functionality.

Annotate.ButtonDownFcn(SRC, EVNT, TYPE) is a static method available to
be executed as a button down callback function. It interactively
creates an annotation object of type TYPE which is automatically pinned
to the axes ancestor of handle SRC.

Annotate.ButtonDownFcn(___, 'PropertyName', Value, ...) interactively
creates the annotation object and applies the settings specified by the
property name/value pairs.

The property 'ParentAnnotation' is added to the annotation object so
its "parent annotation" Annotate object, constructed with the button
down callback function, can be recovered and used to set/get the
annotation position in axes data coordinates.

Examples:

% programmatic placement through constructor
figure; x=0:0.1:6; y=sin(x); h=plot(x,y);
obj1 = Annotate(gca, 'ellipse', [1.5,2.5], [-0.8,0.4]);
obj2 = Annotate(gca, 'arrow', [x(1),x(10)]+0.2, [y(1),y(10)]);
obj3 = Annotate(gca, 'doublearrow', [4,3], [-0.6,0.4], 'linestyle', '--');
obj4 = Annotate(gca, 'line', [1,4], [0.6,0.6], 'color', 'r');
obj4.Position = [0.5,3.5,0.8,0.8]; % set new axes data coordinate position
obj5 = Annotate(gca, 'textbox', [2.5,4.5], [0.8,0.9], 'backgroundcolor', 'none', 'string', 'example textbox');
obj5.Primitive.EdgeColor = 'none'; obj5.Primitive.FontWeight = 'bold';
obj6 = Annotate(gca, 'textarrow', [4.5,x(55)], [0.2,y(55)], 'string', {'Programmatically','input text'});

% interactive placement through button down callback function
figure; x=0:0.1:6; y=sin(x); h=plot(x,y);
set(gca, 'ButtonDownFcn', {@Annotate.ButtonDownFcn, 'textarrow'}); % manually input text, hit escape when done
set(h, 'ButtonDownFcn', {@Annotate.ButtonDownFcn, 'rectangle'}); % can be set for axes child as well
% once created with the button down callback function, a primitive annotation could be set as the current object
% and a new axes data coordinate position could be specified with the following code
% obj = get(gco,'ParentAnnotation'); obj.Position = [1 3 0.0 0.5];

References:

http://undocumentedmatlab.com/blog/pinning-annotations-to-graphs
http://undocumentedmatlab.com/blog/inactive-control-tooltips-event-chaining
http://undocumentedmatlab.com/blog/adding-dynamic-properties-to-graphic-handles
http://undocumentedmatlab.com/blog/ishghandle-undocumented-input-parameter

Cite As

Todd Baxter (2020). Annotate (https://www.mathworks.com/matlabcentral/fileexchange/63760-annotate), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (9)

Todd Baxter

@Turlough - I opted for the undocumented syntax for backwards compatibility purposes. The newer documented property validation syntax requires R2017a or later. I will remove the property validation syntax altogether (and validate properties through a different method) in a future release to remain backwards and forwards compatible.

I used this sample code on a binary image and received the following warning message:

obj5 = Annotate(gca, 'textbox', [2.5,4.5], [0.8,0.9], 'backgroundcolor', 'none', 'string', 'example textbox');

Warning: Class 'Annotate' uses an undocumented syntax to restrict property values. Use property validation syntax instead. This
warning will become an error in a future release.

Jonas Krimmer

Jason Lopez

Works Great! Thank you!

Davide

GreenPiece

Oh, I solved it. Thanks for a useful tool.

GreenPiece

how can I directly enter the string in 'textarrow' mode by the code line without using the pop-up?

Austin Fite

Updates

1.2.1.1

Upload the correct file

1.2.1

Updated formatting and function naming convention

1.2.0.1

Update example image

1.2.0.0

Bug fixes and refactoring for better code reuse

1.1.0.0

HG2 compatibility release along with various bug fixes and improvements

MATLAB Release Compatibility
Created with R2017a
Compatible with any release
Platform Compatibility
Windows macOS Linux