function [pprtpmat] = pprtpconv(spotmat,zlen,pixratio)
% Function PPRTPCONV.M
%
%    [pprtpmat] = pprtpconv(spotmat,zlen,pixratio)
%
%    PPRTPCONV converts pepperpot spot information, in [X,Y] Cartesian
%    coordinates, into spherical polar [r,theta,phi] coordinates, to allow
%    easier calculation of rotated beam data and calculation of emittance
%    angles.  The Z coordinates for each point can either be provided as a
%    single length or as a matrix for each hole.  It also converts between
%    corrdinates given in [number of pixels] to mm (and radians, NOT mrad,
%    for angles), based on a pixels-per-mm ratio, PIXRATIO.
%
%    It is important to note that, due to the way graphics formats number
%    their pixels ie. from top-left to bottom-right, rather than the
%    conventional Cartesian coordinate system of bottom-left to top-right,
%    pixel information extracted from an image is upside down.  As such,
%    PPRTPCONV takes this into account by MAKING THE VERTICAL PIXEL
%    COORDINATES NEGATIVE ie. flipping the vertical axis.  As such, it is
%    preferred that relative, not absolute, pixel information is given ie.
%    the distance from the central pixel/spot.
%
%    In making the convertion, theta is the azimuthal angle from the x-axis
%    (ie. around the z-axis) and phi the polar angle (ie. angle away from
%    the z-axis).  The angle theta=0 corresponds to the x-z plane and phi=0 to
%    the z-axis.
%
%    [PPRTPMAT] = PPRTPCONV(SPOTMAT,ZLEN) converts the [X,Y] pixel
%    information in SPOTMAT into [x,y] and [r,theta,phi] information, in mm
%    and radians, in PPRTPMAT.  Without the additional pixel ratio
%    information, it is assumed that 1 pixel = 1mm.  The
%    dimensions/arrangement of the matrices are as follows:
%
%        SPOTMAT - An [M x N x 2] matrix of horizontal and vertical spot
%                  positions or offsets, in [number of pixels]: the grid
%                  must be M holes by N holes (usually 25 x 25); [M,N,1]
%                  gives the horizontal pixel location of the spot (M,N),
%                  and [M,N,2] the vertical pixel location.
%
%        ZLEN - An [M x N] matrix or a single number, giving longitudinal
%               data in mm (not pixels).
%
%        PPRTPMAT - An [M x N x 5] matrix, where (M,N) corresponds to the
%                   spot position as before; [M,N,1:2] gives the [x,y]
%                   position of each spot, in (mm); [M,N,3:5] gives the
%                   [r,theta,phi] position of each spot in (mm,rad,rad).
%                   The matrix is therefore structured as follows:
%
%                   1: Horz location of spot (mm)
%                   2: Vert location of spot (mm)
%                   3: r distance of spot from origin (mm)
%                   4: theta of line from origin to spot (rad)
%                   5: phi of line from origin to spot (rad)
%
%    [PPRTPMAT] = PPRTPCONV(SPOTMAT,ZLEN,PIXRATIO) also provides the
%    pixels-per-mm ratio, PIXRATIO, to correctly give the output in (mm).
%    The default value is 1.
%

    if nargin < 2
        error('Need at least 2 input variables: [pprtpmat] = pprtpconv(spotmat,zlen,pixratio)') ;
    elseif nargin > 3
        error('Can only specify 3 input variables: [pprtpmat] = pprtpconv(spotmat,zlen,pixratio)') ;
    elseif nargout ~= 1
        error('Must specify only 1 output variable: [pprtpmat] = pprtpconv(spotmat,zlen,pixratio)') ;
    end

    if nargin < 3
        pixratio = 1 ;
    end

%    Make sure zlen is either a single number or the same size as spotmat

    spmsize = size(spotmat) ;
    zsize = size(zlen) ;

    if ( zsize(1) ~= 1 ) & ( zsize(2) ~= 1 )
        if ( spmsize(1) ~= zsize(1) ) | ( spmsize(2) ~= zsize(2) )
            error('zlen must either be a single number or a matrix of the same size as spotmat') ;
        end
    end

%    Calculate r,theta,phi position for spots
%    pprtpmat matrix is ordered as follows:
%
%    1: Horz location of spot (mm)
%    2: Vert location of spot (mm)
%    3: r distance of spot from origin (mm)
%    4: theta of line from origin to spot (rad)
%    5: phi of line from origin to spot (rad)

    pprtpmat = zeros(spmsize(1),spmsize(2),5) ;

%    Main spot positions in (X,Y) and (r,theta,phi)

    pprtpmat(:,:,1) = spotmat(:,:,1)./pixratio ;            %   X
    pprtpmat(:,:,2) = spotmat(:,:,2)./(-pixratio) ;         %   Y
    pprtpmat(:,:,3) = sqrt( pprtpmat(:,:,1).^2 + pprtpmat(:,:,2).^2 + zlen.^2 ) ;   %   r
    pprtpmat(:,:,4) = atan2( pprtpmat(:,:,2),pprtpmat(:,:,1) ) ;                    %   theta
    pprtpmat(:,:,5) = acos( zlen./pprtpmat(:,:,3) ) ;                               %   phi

    return

