function [hLine, hAxes] = animator(varargin)
%ANIMATOR Convenience function for animatorApp
% This is a convenience wrapper function around "animatorApp". You call
% them exactly the same as with "animatorApp", but you don't get any
% objects returned.
%
% ANIMATOR() opens up the animation viewer.
%
% ANIMATOR(X, Y) animates the data. The data has to be in one of the
% following formats. The general form is a 3-D array. 1st dimension is
% the number of elements in a signal (m). 2nd dimension is the number of
% lines (n). 3rd dimension is the number of frames (p).
% 1. X can be either an m by 1 (2D) array or an m by n by p (3D) array.
% If 2D, all frames will use the same X vector
%
% 2. X - m by 1
% Y - m by n by p
% (This is for animating n lines, with a single X vector for ALL of
% p frames)
%
% 3. X - m by 1 by p OR m by n by p
% Y - m by n by p
% (This is for animating n lines, with a fixed X vector for EACH
% of the p frames OR X-Y pairs per frame)
%
% 4. X - [] (empty)
% Y - m by n by p
% (Y will be animated against it's index 1:m)
%
% ANIMATOR(X, Y, PARAM1, VALUE1, ...) accepts additional arguments:
% 'axis' : {'auto'}, 'equal
% 'xlim' : 'auto', [XMIN, XMAX]. Default uses the full range
% 'ylim' : 'auto', [YMIN, YMAX]. Default uses the full range
% 'title' : <title text>
% 'xlabel' : <xlabel text>
% 'ylabel' : <ylabel text>
% 'smooth' : {'off'}, 'on'. Anti-aliasing
% 'frame' : {1}. Starting frame number
% 'speed' : {9}. Integer between -10 and 10. 10 is fastest, -10 is
% fastest in the reverse direction.
% 'framerate': {1}, 2, 3, 5, 10. Animate every # frames.
%
% [hLine, hAxes] = ANIMATOR(...) returns the handles for the lines and
% the axes. This allows for customizing of the objects.
%
% GUI Features:
% The controls allows you to speed up and slow down (or reverse) the
% playback. You can pause at any time. You can also drag the time line
% bar to go to arbitrary frames. Also, use the arrow keys to move between
% frames (left or right) or change the speed (up or down). Spacebar
% pauses/starts the animation. In addition to the animation speed, the
% animation frame interval rate can be set from the menu.
%
% The graphics properties can be customized via a context menu on the
% objects. Right-click on the plotted lines to bring up the context menu.
%
% The animation can be exported to an AVI (R2010b or newer) or an
% Animated GIF. The Animated GIF option requires the Image Processing
% Toolbox (if R2008b or older), for converting RGB to Indexed data.
%
% Example 1:
% x = (0:.01:10)';
% y = nan(length(x), 2, 400);
% for idx = 1:400;
% y(:, 1, idx) = sin(2*x) + cos(0.25*sqrt(idx)*x);
% y(:, 2, idx) = -cos(0.7*x) + sin(0.4*sqrt(idx)*x);
% end
% ANIMATOR(x, y);
%
% Example 2:
% load animatorSampleData;
%
% % Vibrating string
% [hL] = ANIMATOR(X1,Y1,'ylim',[-.7 .7],'title','Vibrating String','smooth','on');
% set(hL, 'marker', 'o');
%
% % Two double-pendulum
% [hL, hAx] = ANIMATOR(X2,Y2,'axis','equal','title','Double Double-Pendulum');
% set(hL, 'LineWidth', 3, 'Marker', '.', 'MarkerSize', 20);
% set(hAx, 'XGrid', 'on', 'YGrid', 'on');
%
% See also animatorApp.
% Versions:
% v1.0 - Original version (Aug, 2007)
% v1.1 - Added option for specifying initial frame and animation speed
% v2.0 - Added exporting option (AVI or Animated GIF) (Nov, 2007)
% v2.1 - Added settings dialog for AVI and Animated GIF (Nov, 2007)
% v2.3 - Refactor functions (Nov, 2007)
% v2.4 - Changed graphics to Painters. Some graphics card has problems (Oct 2008)
% v2.5 - Changed back to OpenGL.
% v3.0 - Converted to object oriented code and added the ability to load
% different data sets (Aug 2012)
%
% Jiro Doke
% Copyright 2007-2012 The MathWorks, Inc.
app = animatorApp(varargin{:});
error(nargoutchk(0, 2, nargout, 'struct')); %#ok<NCHKE> % for backwards compatibility
if nargout > 0
hLine = app.hLine;
end
if nargout > 1
hAxes = app.hAxes;
end
end
