function [cent,stdxy,spint] = ppspot(immat,spot,width,imcut)
% Function PPSPOT.M
%
%    [cent,stdxy,spint] = ppspot(immat,spot,width,imcut)
%
%    PPSPOT finds the weighted centre of a set of pixels within an image.
%    The image matrix IMMAT must be a grayscale image.  PPSPOT calls the
%    function PPCENTRE to calculate the weighted centre of a group of
%    sub-pixels.  This sub-group is selected from the main image matrix by
%    specifying a centre point and a width.  In addition, a cut can be
%    applied to the intensity.
%
%    PPSPOT(IMMAT,SPOT,WIDTH) finds the centre of an area within the image
%    matrix IMMAT.  The centre of the area is defined by SPOT, where 
%    SPOT = [XPIX YPIX] and the width of the area to search (both
%    horizontal and vertical) is defined by WIDTH pixels.  The area is then
%    displayed on screen.
%
%    Since PPSPOT only deals in whole pixels, WIDTH should be an odd
%    number; otherwise the width is rounded up to the nearest odd number.
%    The pixel location SPOT should be a whole number: PPSPOT automatically
%    rounds it to the nearest whole pixel number before creating the
%    sub-image.
%
%    PPSPOT(IMMAT,SPOT,WIDTH,IMCUT) also applies a cut to the image data,
%    removing pixel intensities below the intensity level IMCUT by
%    subtracting the grayscale value IMCUT from each pixel value, then
%    making the minimum value of any pixel zero.
%
%    [CENT] = PPSPOT(IMMAT,SPOT,WIDTH,IMCUT) outputs the central pixel
%    location to the variable CENT.  CENT is a weighted average and is not
%    rounded off to the nearest pixel value.
%
%    [CENT,STDXY] = PPSPOT(IMMAT,SPOT,WIDTH,IMCUT) also outputs the
%    horizontal and vertical standard deviations to the variable STDXY.
%
%    [CENT,STDXY,SPINT] = PPSPOT(IMMAT,SPOT,WIDTH,IMCUT) also outputs the
%    Spot Intensity ie. the sum of all the pixel intensities in the
%    specified image, to the variable SPINT.
%

    if nargin < 3
        error('Need at least 3 input variables: [cent,stdxy,spint] = ppspot(immat,spot,width)') ;
    elseif nargin > 4
        error('Can only specify 4 input variables: [cent,stdxy,spint] = ppspot(immat,spot,width,imcut)') ;
    elseif nargout > 3
        error('Can only specify 2 output variables: [cent,stdxy,spint] = ppspot(immat,spot,width,imcut)') ;
    end

    if nargin < 4
        imcut = 0 ;
    end

    imsize = size(immat) ;

%    Select sub-pixel image from main matrix using spot position

    spotrad = round( ( width - 1)./2 ) ;
    spotro = round( spot ) ;
%    disp(['X: ' num2str(spotro(2) - spotrad) ' to ' num2str(spotro(2) + spotrad) ' pixels']) ;
%    disp(['Y: ' num2str(spotro(1) - spotrad) ' to ' num2str(spotro(1) + spotrad) ' pixels']) ;

    if ( ( spotro(2) - spotrad ) <= 0 ) | ( ( spotro(1) - spotrad ) <= 0 ) | ...
            ( ( spotro(2) + spotrad ) > imsize(1) ) | ( ( spotro(1) + spotrad ) > imsize(2) )

        cent = spot ;
        stdxy = 0 ;
        spint = 0 ;

    else

        subim = immat(((spotro(2) - spotrad):(spotro(2) + spotrad)), ((spotro(1) - spotrad):(spotro(1) + spotrad))) ;

%    Use PPCENTRE to find image centre and standard deviations

        [spotcent,stdxy,spint] = ppcentre(subim,imcut) ;

        if spint <= 0
            cent = spot ;
        else
            cent = [(spotcent(1) + spotro(1) - spotrad - 1) (spotcent(2) + spotro(2) - spotrad - 1)] ;
        end

    end

    if nargout == 0
        disp(' ')
        disp(['Image centre is at  ' num2str(cent) ' pixels.']) ;
        disp(' ')
    end

    return