Matlab矢量图图例函数quiverkey

Matlab自带函数中不包含构造 quiver 函数注释过程，本文参照 matplotlib 中 quiverkey 函数，构造类似函数为 Matlab 中 quiver 矢量场进行标注。

quiverkey函数

首先看 matplotlib 中 quiverkey 如何定义的

quiverkey(*args, **kw)
Add a key to a quiver plot.

Call signature::

quiverkey(Q, X, Y, U, label, **kw)

Arguments:

Q:
The Quiver instance returned by a call to quiver.

X, Y:
The location of the key; additional explanation follows.

U:
The length of the key

label:
A string with the length and units of the key

Keyword arguments:

coordinates = [ 'axes' | 'figure' | 'data' | 'inches' ]
Coordinate system and units for X, Y: 'axes' and 'figure' are
normalized coordinate systems with 0,0 in the lower left and 1,1
in the upper right; 'data' are the axes data coordinates (used for
the locations of the vectors in the quiver plot itself); 'inches'
is position in the figure in inches, with 0,0 at the lower left
corner.

color:
overrides face and edge colors from Q.

labelpos = [ 'N' | 'S' | 'E' | 'W' ]
Position the label above, below, to the right, to the left of the
arrow, respectively.

labelsep:
Distance in inches between the arrow and the label. Default is
0.1

labelcolor:
defaults to default :class:~matplotlib.text.Text color.

fontproperties:
A dictionary with keyword arguments accepted by the
:class:~matplotlib.font_manager.FontProperties initializer:
family, style, variant, size, weight

Any additional keyword arguments are used to override vector
properties taken from Q.

The positioning of the key depends on X, Y, coordinates, and
labelpos. If labelpos is 'N' or 'S', X, Y give the position
of the middle of the key arrow. If labelpos is 'E', X, Y
positions the head, and if labelpos is 'W', X, Y positions the
tail; in either of these two cases, X, Y is somewhere in the
middle of the arrow+label key object.

Additional kwargs: hold = [True|False] overrides default hold state

可以看到主要参数有这么些个

1. quiver绘图指针
2. 图例位置 X, Y
3. 标注大小 U
4. 标注单位字符
5. 其他参数
   1）. 输入坐标 X, Y 单位
   2）. （文字）标注在图例哪个位置
   3）. 标注与图例相对距离
   4）. 标注字体颜色

使用方法：

对应Matlab函数也应该使用这么个流程

1. 使用quiver绘图
2. 将quiver返回指针与图例位置坐标和大小等作为参数传入

示例

[x,y] = meshgrid(0:0.2:2,0:0.2:2);
u = cos(x).*y;
v = sin(x).*y;

figure; 
Qh = quiver(x,y,u,v);

quiverkey(Qh, 0.5, 2.5, 1, 'm/s', 'Color', 'r', 'Coordinates', 'data')

最终效果图

代码

function Q = quiverkey(Q, X, Y, U, label, varargin)
%QUIVERKEY legend for quiver
%
%   QUIVERKEY(Q, X, Y, U, label) 
%   
%   Arguments:
%       Q :      The quiver handle returned by a call to quiver
%       X,Y :    The location of the legend
%       U :      The unit length. If U<0, the arrow will be reversed
%       label :  The string with the length and units of the key
%   
%   Addition arguments:
%       Coordinates = [ 'axes' | 'data'(default) ]
% 
%           'axes' & 'figure' : 'axes' and 'figure' are normalized 
%                       coordinate systems with 0,0 in the lower left 
%                       and 1,1 in the upper right;
%           'data' :    use the axes data coordinates
% 
%       LabelDistance : Distance in 'coordinates' between the arrow and the
%                   label. Deauft is 0.1 (units 'axes').
% 
%       Color : overrides face and edge colors from Q.
% 
%       LabelPosition = [ 'N' | 'S'(default) | 'E' | 'W' ]
% 
%               Position the label above, below, to the right, 
%               to the left of the arrow, respectively.
% 
%       LabelColor : defaults to black
%       
%   Examples: 
% 
%   [x,y] = meshgrid(0:0.2:2,0:0.2:2);
%   u = cos(x).*y;
%   v = sin(x).*y;
%   figure; Qh = quiver(x,y,u,v);
%   quiverkey(Qh, 0.5, 2.5, 1, 'm/s', 'Color', 'r', 'Coordinates', 'data')
%   
% Author:
%   li12242 - Department of Civil Engineering in Tianjin University
% Email:
%   li12242@tju.edu.cn
% 

%% get input argument
if nargin < 5 
    error('Input arguments" Number incorrect!')
end

if isempty(varargin) && mod(length(varargin), 2) ~= 0
    error('Input arguments donot pairs!')
else
    [CoorUnit, LabelDist, Color, LabelPosition, LabelColor] = getInput(varargin);
end


%% add legend arrow

% get original data
xData = get(Q, 'XData'); yData = get(Q, 'YData');
uData = get(Q, 'UData'); vData = get(Q, 'VData');

% get axes properties
haxes = get(Q, 'Parent');
xLim = get(haxes, 'XLim'); yLim = get(haxes, 'YLim');
NextPlot = get(haxes, 'NextPlot');

% set axes properties
set(haxes, 'NextPlot', 'add')

if strcmp(CoorUnit, 'axes')
    % position of legend arrow
    xa = xLim(1) + X*(xLim(2) - xLim(1));
    ya = yLim(1) + Y*(yLim(2) - yLim(1));
else
    xa = X; ya = Y;
end

% add legend arrow into data vector
xData = [xData(:); xa]; yData = [yData(:); ya];
uData = [uData(:); U];  vData = [vData(:); 0];

% reset data
set(Q, 'XData', xData, 'YData', yData, 'UData', uData, 'VData', vData);
set(Q, 'Color', Color)

%% add text
dx = LabelDist*(xLim(2) - xLim(1));
dy = LabelDist*(yLim(2) - yLim(1));

% set position of label
switch LabelPosition
    case 'N'
        xl = xa; yl = ya + dy;
    case 'S'
        xl = xa; yl = ya - dy;
    case 'E'
        xl = xa + dx; yl = ya;
    case 'W'
        xl = xa - dx; yl = ya;
end% switch

th = text(xl, yl, [num2str(U), ' ', label]);
set(th, 'Color', LabelColor);

% turn axes properties to original
set(haxes, 'NextPlot', NextPlot)

end% func

%% sub function

function [CoorUnit, LabelDist, Color, LabelPosition, LabelColor] = getInput(varcell)
% Input:
%   varcell - cell variable
% Output:
% 
nargin = numel(varcell);

%% set default arguments

CoorUnit = 'data';
LabelDist = 0.05; % units 'axes'
Color = 'k';
LabelPosition = 'S';
LabelColor = 'k';

%% get input arguments
contour = 1;
while contour < nargin
    switch varcell{contour}
        case 'Coordinates'
            CoorUnit = varcell{contour+ 1};
        case 'LabelDistance'
            LabelDist = varcell{contour+ 1};
        case 'Color'
            Color = varcell{contour+ 1};
        case 'LabelPosition'
            LabelPosition = varcell{contour+ 1};
        case 'LabelColor'
            LabelColor = varcell{contour+ 1};
        otherwise
            error('Unknown input argument.')
    end% switch
    contour = contour + 2;
end% while

end% fun