| Current File : //usr/man/man3mlib/mlib_ImageNormCrossCorrel_Fp.3mlib |
'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.TH mlib_ImageNormCrossCorrel_Fp 3MLIB "2 Mar 2007" "SunOS 5.11" "mediaLib Library Functions"
.SH NAME
mlib_ImageNormCrossCorrel_Fp \- normalized cross correlation
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \fB-lmlib\fR [ \fIlibrary\fR... ]
#include <mlib.h>
\fBmlib_status\fR \fBmlib_ImageNormCrossCorrel_Fp\fR(\fBmlib_d64 *\fR\fIcorrel\fR,
\fBconst mlib_image *\fR\fIimg1\fR, \fBconst mlib_image *\fR\fIimg2\fR, \fBconst mlib_d64 *\fR\fImean2\fR,
\fBconst mlib_d64 *\fR\fIsdev2\fR);
.fi
.SH DESCRIPTION
.sp
.LP
The \fBmlib_ImageNormCrossCorrel_Fp()\fR function computes the normalized cross-correlation coefficients between a pair of floating-point images, on a per-channel basis.
.sp
.LP
It uses the following equations:
.sp
.in +2
.nf
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
.fi
.in -2
.sp
.LP
where \fBw\fR and \fBh\fR are the width and height of the images, respectively; \fBm1\fR and \fBm2\fR are the mean arrays of the first and second images, respectively; \fBs1\fR and \fBs2\fR are the un-normalized standard deviation arrays of the first and second images, respectively.
.sp
.LP
In usual cases, the normalized cross-correlation coefficient is in the range of \fB[-1.0, 1.0]\fR. In the case of \fB(s1[i] == 0)\fR or \fB(s2[i] == 0)\fR, where a constant image channel is involved, the normalized cross-correlation coefficient is defined as follows:
.sp
.in +2
.nf
#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;
}
}
.fi
.in -2
.sp
.LP
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 \fBMLIB_FLOAT\fR or \fBMLIB_DOUBLE\fR.
.sp
.LP
If \fB(mean2 == NULL)\fR or \fB(sdev2 == NULL)\fR, then \fBm2\fR and \fBs2\fR are calculated in this function according to the formulas shown above. Otherwise, they are calculated as follows:
.sp
.in +2
.nf
m2[i] = mean2[i];
s2[i] = sdev2[i] * sqrt(w*h);
.fi
.in -2
.sp
.LP
where \fBmean2\fR and \fBsdev2\fR can be the output of \fBmlib_ImageMean()\fR and \fBmlib_ImageStdDev()\fR, respectively.
.sp
.LP
In some cases, the resulting coefficients of this function could be NaN, Inf, or -Inf.
.SH PARAMETERS
.sp
.LP
The function takes the following arguments:
.sp
.ne 2
.mk
.na
\fB\fIcorrel\fR\fR
.ad
.RS 10n
.rt
Pointer to normalized cross correlation array on a channel basis. The array must be the size of channels in the images. \fBcorrel[i]\fR contains the cross-correlation of channel \fBi\fR.
.RE
.sp
.ne 2
.mk
.na
\fB\fIimg1\fR\fR
.ad
.RS 10n
.rt
Pointer to first image.
.RE
.sp
.ne 2
.mk
.na
\fB\fIimg2\fR\fR
.ad
.RS 10n
.rt
Pointer to second image.
.RE
.sp
.ne 2
.mk
.na
\fB\fImean2\fR\fR
.ad
.RS 10n
.rt
Pointer to the mean array of the second image.
.RE
.sp
.ne 2
.mk
.na
\fB\fIsdev2\fR\fR
.ad
.RS 10n
.rt
Pointer to the standard deviation array of the second image.
.RE
.SH RETURN VALUES
.sp
.LP
The function returns \fBMLIB_SUCCESS\fR if successful. Otherwise it returns \fBMLIB_FAILURE\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE
.SH SEE ALSO
.sp
.LP
\fBmlib_ImageAutoCorrel\fR(3MLIB), \fBmlib_ImageAutoCorrel_Fp\fR(3MLIB), \fBmlib_ImageCrossCorrel\fR(3MLIB), \fBmlib_ImageCrossCorrel_Fp\fR(3MLIB), \fBmlib_ImageNormCrossCorrel\fR(3MLIB), \fBattributes\fR(5)