1######################################################################## 2## 3## Copyright (C) 2007-2021 The Octave Project Developers 4## 5## See the file COPYRIGHT.md in the top-level directory of this 6## distribution or <https://octave.org/copyright/>. 7## 8## This file is part of Octave. 9## 10## Octave is free software: you can redistribute it and/or modify it 11## under the terms of the GNU General Public License as published by 12## the Free Software Foundation, either version 3 of the License, or 13## (at your option) any later version. 14## 15## Octave is distributed in the hope that it will be useful, but 16## WITHOUT ANY WARRANTY; without even the implied warranty of 17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18## GNU General Public License for more details. 19## 20## You should have received a copy of the GNU General Public License 21## along with Octave; see the file COPYING. If not, see 22## <https://www.gnu.org/licenses/>. 23## 24######################################################################## 25 26## -*- texinfo -*- 27## @deftypefn {} {} feather (@var{u}, @var{v}) 28## @deftypefnx {} {} feather (@var{z}) 29## @deftypefnx {} {} feather (@dots{}, @var{style}) 30## @deftypefnx {} {} feather (@var{hax}, @dots{}) 31## @deftypefnx {} {@var{h} =} feather (@dots{}) 32## 33## Plot the @code{(@var{u}, @var{v})} components of a vector field emanating 34## from equidistant points on the x-axis. 35## 36## If a single complex argument @var{z} is given, then 37## @code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}. 38## 39## The style to use for the plot can be defined with a line style @var{style} 40## of the same format as the @code{plot} command. 41## 42## If the first argument @var{hax} is an axes handle, then plot into this axes, 43## rather than the current axes returned by @code{gca}. 44## 45## The optional return value @var{h} is a vector of graphics handles to the 46## line objects representing the drawn vectors. 47## 48## @example 49## @group 50## phi = [0 : 15 : 360] * pi/180; 51## feather (sin (phi), cos (phi)); 52## @end group 53## @end example 54## 55## @seealso{plot, quiver, compass} 56## @end deftypefn 57 58function h = feather (varargin) 59 60 [hax, varargin, nargin] = __plt_get_axis_arg__ ("feather", varargin{:}); 61 62 if (nargin == 0 || nargin > 3) 63 print_usage (); 64 endif 65 66 if (nargin == 1 || (nargin == 2 && ! isnumeric (varargin{2}))) 67 z = varargin{1}(:).'; 68 u = real (z); 69 v = imag (z); 70 have_line_spec = (nargin == 2); 71 elseif (nargin >= 2 && isnumeric (varargin{2})) 72 ioff = 3; 73 u = varargin{1}(:).'; 74 v = varargin{2}(:).'; 75 have_line_spec = (nargin == 3); 76 else 77 print_usage (); 78 endif 79 80 arrowsize = 0.20; 81 line_spec = "-b"; 82 83 if (have_line_spec) 84 arg = varargin{end}; 85 if (ischar (arg) || iscellstr (arg)) 86 [~, valid] = __pltopt__ ("feather", arg, false); 87 if (valid) 88 line_spec = arg; 89 else 90 error ("feather: invalid linestyle STYLE"); 91 endif 92 else 93 error ("feather: invalid linestyle STYLE"); 94 endif 95 endif 96 97 ## Matlab draws feather plots, with the arrow head as one continuous line, 98 ## and each arrow separately. This is completely different from quiver and 99 ## quite ugly. 100 n = length (u); 101 xend = [1 : n] + u; 102 xtmp = [1 : n] + u .* (1 - arrowsize); 103 yend = v; 104 ytmp = v .* (1 - arrowsize); 105 x = [[1 : n]; xend; xtmp - v * arrowsize / 3; xend; ... 106 xtmp + v * arrowsize / 3]; 107 y = [zeros(1, n); yend; ytmp + u * arrowsize / 3; yend; ... 108 ytmp - u * arrowsize / 3]; 109 110 oldfig = []; 111 if (! isempty (hax)) 112 oldfig = get (0, "currentfigure"); 113 endif 114 unwind_protect 115 hax = newplot (hax); 116 htmp = plot (x, y, line_spec, [1, n], [0, 0], line_spec); 117 unwind_protect_cleanup 118 if (! isempty (oldfig)) 119 set (0, "currentfigure", oldfig); 120 endif 121 end_unwind_protect 122 123 if (nargout > 0) 124 h = htmp; 125 endif 126 127endfunction 128 129 130%!demo 131%! clf; 132%! phi = [0 : 15 : 360] * pi/180; 133%! feather (sin (phi), cos (phi)); 134%! axis tight; 135%! title ("feather plot"); 136 137## Test input validation 138%!error feather () 139%!error feather (1,2,3,4) 140%!error feather (1, "-r", 2) 141%!error <invalid linestyle STYLE> feather (1, "abc") 142%!error <invalid linestyle STYLE> feather (1, {1}) 143