mlib_ImageNormCrossCorrel_Fp(3MLIB)									       mlib_ImageNormCrossCorrel_Fp(3MLIB)

NAME

       mlib_ImageNormCrossCorrel_Fp - normalized cross correlation

SYNOPSIS

       cc [ flag... ] file... -lmlib [ library... ]
       #include <mlib.h>

       mlib_status  mlib_ImageNormCrossCorrel_Fp(mlib_d64  *correl,  const  mlib_image *img1, const mlib_image *img2, const mlib_d64 *mean2, const
       mlib_d64 *sdev2);

       The mlib_ImageNormCrossCorrel_Fp() function computes the normalized cross-correlation coefficients between a pair of floating-point images,
       on a per-channel basis.

       It uses the following equations:

		      w-1 h-1
		      SUM SUM (d1[x][y][i] * d2[x][y][i])
		      x=0 y=0
	 correl[i] = -------------------------------------
				s1[i] * s2[i]

       d1[x][y][i] = img1[x][y][i] - m1[i]

       d2[x][y][i] = img2[x][y][i] - m2[i]

		       1     w-1 h-1
	     m1[i] = ----- * SUM SUM img1[x][y][i]
		      w*h    x=0 y=0

		       1     w-1 h-1
	     m2[i] = ----- * SUM SUM img2[x][y][i]
		      w*h    x=0 y=0

			   w-1 h-1
	     s1[i] = sqrt{ SUM SUM (img1[x][y][i] - m1[i])**2 }
			   x=0 y=0

			   w-1 h-1
	     s2[i] = sqrt{ SUM SUM (img2[x][y][i] - m2[i])**2 }
			   x=0 y=0

       where  w  and h are the width and height of the images, respectively; m1 and m2 are the mean arrays of the first and second images, respec-
       tively; s1 and s2 are the un-normalized standard deviation arrays of the first and second images, respectively.

       In usual cases, the normalized cross-correlation coefficient is in the range of [-1.0, 1.0].  In the case of (s1[i] == 0) or (s2[i] ==  0),
       where a constant image channel is involved, the normalized cross-correlation coefficient is defined as follows:

	   #define signof(x) ((x > 0) ? 1 : ((x < 0) ? -1 : 0))

	   if ((s1[i] == 0.) || (s2[i] == 0.)) {
	       if ((s1[i] == 0.) && (s2[i] == 0.)) {
		  if (signof(m1[i]) == signof(m2[i]) {
		      correl[i] = 1.0;
		  } else {
		      correl[i] = -1.0;
		  }
	       } else {
		   correl[i] = -1.0;
	       }
	   }

       The  two  images must have the same type, the same size, and the same number of channels. They can have 1, 2, 3 or 4 channels.  They can be
       of type MLIB_FLOAT or MLIB_DOUBLE.

       If (mean2 == NULL) or (sdev2 == NULL), then m2 and s2 are calculated in this function according to the formulas	shown  above.	Otherwise,
       they are calculated as follows:

	   m2[i] = mean2[i];
	   s2[i] = sdev2[i] * sqrt(w*h);

       where mean2 and sdev2 can be the output of mlib_ImageMean() and mlib_ImageStdDev(), respectively.

       In some cases, the resulting coefficients of this function could be NaN, Inf, or -Inf.

       The function takes the following arguments:

       correl	       Pointer	to  normalized	cross  correlation array on a channel basis. The array must be the size of channels in the images.
		       correl[i] contains the cross-correlation of channel i.

       img1	       Pointer to first image.

       img2	       Pointer to second image.

       mean2	       Pointer to the mean array of the second image.

       sdev2	       Pointer to the standard deviation array of the second image.

       The function returns MLIB_SUCCESS if successful. Otherwise it returns MLIB_FAILURE.

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

       mlib_ImageAutoCorrel(3MLIB), mlib_ImageAutoCorrel_Fp(3MLIB), mlib_ImageCrossCorrel(3MLIB), mlib_ImageCrossCorrel_Fp(3MLIB), mlib_ImageNorm-
       CrossCorrel(3MLIB), attributes(5)

								    23 May 2005 			       mlib_ImageNormCrossCorrel_Fp(3MLIB)