function [uamp, upha, vamp, vpha, w]=ell2uv(maj, ecc, inc, pha)
% Convert tidal ellipse parameters into U and V amp and phase lag parameters.
%  (inverse of routine uv2ell.m)
%
%   Usage:   [uamp, upha, vamp, vpha, w]=ell2uv(maj, ecc, inc, pha)
%
%   Inputs:  maj = major axis (semi-major axis) amplitude
%            ecc  = ellipticity (minor axis amplitude/major axis amplitude). 
%                     (Note:  ecc is negative if the ellipse rotates clockwise. )
%            inc  = inclination angle (degrees) from x-axis to major axis 
%            pha  = phase angle (degrees) for time of maximum current (directed 
%                         outward along angle inc)
%
%            input arguments can be scalars, vectors or matrices (all same size).
%
%     w:    Optional. If it is requested, this matrix contains the outlines
%           of the calculated ellipses (for plotting purposes).  This matrix will
%           have one dimension greater than your input arrays.  
%           Usage example:  You input 100x50 arrays of values and you want to see
%           the ellipse at (50,4).  You type:  
%                       zi=squeeze(w(50,4,:));
%                       polar(angle(zi),abs(zi));
%
%  Outputs:  uamp, upha, vamp, vpha are the amplitudes and phase lags (degrees) of
%               u- and v- tidal current components. They can be vectors or
%               matrices;
% Zhigang Xu
% April 6, 2000

% Modified by Rich Signell (October 16, 2000):
%  1) changed the definition of "wp" to the complex amplitude of 
%     the positively rotating component (not the complex conjugate as in 
%     the original code.)
%
%  2) Fixed the creation of "w" (the ellipse outline) so that it would 
%     work with arbitrary sized arrays. 
% 
%  3) Added Usage statement to the help
%
% Document:  tidal_ellipse_v2.ps
% 
   Wp = (1+ecc)/2.*maj;
   Wm = (1-ecc)/2.*maj;
   THETAp = inc-pha;
   THETAm = inc+pha;

   %convert degress into radians
   THETAp = THETAp/180*pi;
   THETAm = THETAm/180*pi;

   %Calculate wp and wm.
   wp = Wp.*exp( i*THETAp);
   wm = Wm.*exp( i*THETAm);
   
   if nargout == 5
      ndot=36;
      dot = 2*pi/ndot;
      ot = [0:dot:2*pi-dot];
      w = wp(:)*exp(i*ot)+wm(:)*exp(-i*ot);
      [m,n,p]=size(wp);
      w=squeeze(reshape(w,m,n,p,ndot));
   end

   % Calculate cuamp, cvamp --- complex amplitude of u and v
   cuamp = conj(wp)+wm;
   cvamp = -i*(wm-conj(wp));
   uamp  = abs(cuamp);
   vamp  = abs(cvamp);   
   
% flip angles in the range of [-180 0) to the range of [180 360).
   upha = mod(angle(cuamp)*180/pi,360);
   vpha = mod(angle(cvamp)*180/pi,360);
   

%Author Copyright:
%
%    The author of this program retains the copyright of this program, while
% you are welcome to use and distribute this program as long as you credit 
% the author properly. Particularly, you are expected to retain the
% original author's name in this original version of the program 
% or any of its modifcations that you might make.  Enjoy my programs!
%
% Author Info:
%_______________________________________________________________________
%  Zhigang Xu, Ph.D.                            
%  (pronounced as Tsi Gahng Hsu)
%  Research Scientist
%  Coastal Circulation                   
%  Bedford Institute of Oceanography     
%  1 Challenge Dr.
%  P.O. Box 1006                    Phone  (902) 426-2307 (o)       
%  Dartmouth, Nova Scotia           Fax    (902) 426-7827            
%  CANADA B2Y 4A2                   email zhigangx@emerald.bio.dfo.ca    
%_______________________________________________________________________
%
