# imMlGauss

## PURPOSE

Calculates max likelihood params of Gaussian that gave rise to image G.

## SYNOPSIS

function varargout = imMlGauss( G, symmFlag, show )

## DESCRIPTION

     Calculates max likelihood params of Gaussian that gave rise to image G.

     Suppose G contains an image of a gaussian distribution.  One way to
     recover the parameters of the gaussian is to threshold the image, and
     then estimate the mean/covariance based on the coordinates of the
     thresholded points.  A better method is to do no thresholding and instead
     use all the coordinates, weighted by their value. This function does the
     latter, except in a very efficient manner since all computations are done
     in parallel over the entire image.

     This function works over 2D or 3D images.  It makes most sense when G in
     fact contains an image of a single gaussian, but a result will be
     returned regardless.  All operations are performed on abs(G) in case it
     contains negative or complex values.

     symmFlag is an optional flag that if set to 1 then imMlGauss recovers
     the maximum likelihood symmetric gaussian.  That is the variance in each
     direction is equal, and all covariance terms are 0.  If symmFlag is set
     to 2 and G is 3D, imMlGauss recovers the ML guassian with equal
     variance in the 1st 2 dimensions (row and col) and all covariance terms
     equal to 0, but a possibly different variance in the 3rd (z or t)
     dimension.

     USAGE
      varargout = imMlGauss( G, [symmFlag], [show] )

     INPUTS
      G        - image of a gaussian (weighted pixels)
      symmFlag - [0] see above
      show     - [0] figure to use for optional display

     OUTPUTS
      mu       - 2 or 3 element vector specifying the mean [row,col,z]
      C        - 2x2 or 3x3 covariance matrix [row,col,z]
      GR       - image of the recovered gaussian (faster if omitted)
      logl     - log likelihood of G given recov. gaussian (faster if omitted)

     EXAMPLE - 2D
      R = rotationMatrix( pi/6 );  C=R'*[10^2 0; 0 20^2]*R;
      G = filterGauss( [200, 300], [150,100], C, 0 );
      [mu,C,GR,logl] = imMlGauss( G, 0, 1 );
      mask = maskEllipse( size(G,1), size(G,2), mu, C );
      figure(2); im(mask)

     EXAMPLE - 3D
      R = rotationMatrix( [1,1,0], pi/4 );
      C = R'*[5^2 0 0; 0 2^2 0; 0 0 4^2]*R;
      G = filterGauss( [50,50,50], [25,25,25], C, 0 );
      [mu,C,GR,logl] = imMlGauss( G, 0, 1 );

     See also GAUSS2ELLIPSE, PLOTGAUSSELLIPSES, MASKELLIPSE

     Piotr's Image&Video Toolbox      Version 2.0
     Copyright 2008 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Lesser GPL [see external/lgpl.txt]

## CROSS-REFERENCE INFORMATION

This function calls:

- filterGauss n-dimensional Gaussian filter.
- im Function for displaying grayscale images.
- montage2 Used to display collections of images and videos.
- plotGaussEllipses Plots 2D ellipses derived from 2D Gaussians specified by mus & Cs.

This function is called by: