Census Correlation

Macros
#define	vc_corr_census_32x32(Search, pat, patNr)   vc_corr_census(Search, pat, patNr, 32, 32, &FL_census32x32_32U32, &FL_hamming_32U32)
	"Normalized" Correlation using Census Transform and Hamming Distance (32x32 Pattern). More...
#define	vc_corr_census_48x48(Search, pat, patNr)   vc_corr_census(Search, pat, patNr, 48, 48, &FL_census48x48_72U32, &FL_hamming_72U32)
	"Normalized" Correlation using Census Transform and Hamming Distance (48x48 Pattern). More...
#define	vc_corr_census_pattern_init_32x32(pat, resultMaxNr, imgPat, imgMask, corrMinVal, distHor, distVer)   vc_corr_census_pattern_init(pat, resultMaxNr, imgPat, imgMask, corrMinVal, distHor, distVer, 32, 32, &FL_census32x32_32U32, &FL_hamming_32U32)
	Pattern Initialisation for "Normalized" Correlation using Census Transform and Hamming Distance (32x32 Pattern). More...
#define	vc_corr_census_pattern_init_48x48(pat, resultMaxNr, imgPat, imgMask, corrMinVal, distHor, distVer)   vc_corr_census_pattern_init(pat, resultMaxNr, imgPat, imgMask, corrMinVal, distHor, distVer, 48, 48, &FL_census48x48_72U32, &FL_hamming_72U32)
	Pattern Initialisation for "Normalized" Correlation using Census Transform and Hamming Distance (48x48 Pattern). More...
#define	vc_corr_census_pattern_deinit_32x32(pat)   vc_corr_census_pattern_deinit(pat, 32, 32)
	Pattern Deinitialisation for "Normalized" Correlation using Census Transform and Hamming Distance (32x32 Pattern). More...
#define	vc_corr_census_pattern_deinit_48x48(pat)   vc_corr_census_pattern_deinit(pat, 48, 48)
	Pattern Deinitialisation for "Normalized" Correlation using Census Transform and Hamming Distance (48x48 Pattern). More...

Functions
I32	vc_corr_census (image *Search, VCCorrCensusPattern *pat, I32 patNr, I32 mustKx, I32 mustKy, void(*fn_census_XU32)(U32 pitch, U32 *sumX, U8 *src, U32 *dst), I32(*fn_hamming_XU32)(U32 *src1, U32 *src2))
	"Normalized" Correlation using Census Transform and Hamming Distance. More...
I32	vc_corr_census_pattern_init (VCCorrCensusPattern *pat, I32 resultMaxNr, image *imgPat, image *imgMask, I32 corrMinVal, I32 distHor, I32 distVer, I32 mustKx, I32 mustKy, void(*fn_census_XU32)(U32 pitch, U32 *sumX, U8 *src, U32 *dst), I32(*fn_hamming_XU32)(U32 *src1, U32 *src2))
	Pattern Initialisation for "Normalized" Correlation using Census Transform and Hamming Distance. More...
I32	vc_corr_census_pattern_deinit (VCCorrCensusPattern *pat, I32 mustKx, I32 mustKy)
	Pattern Deinitialisation for "Normalized" Correlation using Census Transform and Hamming Distance. More...

Detailed Description

Macro Definition Documentation

vc_corr_census_32x32

#define vc_corr_census_32x32	(		Search,
			pat,
			patNr
	)		vc_corr_census(Search, pat, patNr, 32, 32, &FL_census32x32_32U32, &FL_hamming_32U32)

This macro is a convenience call for using the census transform with a 32x32 pattern.

vc_corr_census_32x32() is a macro which calls vc_corr_census().

See also

vc_corr_census_pattern_init_32x32(), vc_corr_census_pattern_deinit_32x32().

vc_corr_census_48x48

#define vc_corr_census_48x48	(		Search,
			pat,
			patNr
	)		vc_corr_census(Search, pat, patNr, 48, 48, &FL_census48x48_72U32, &FL_hamming_72U32)

This macro is a convenience call for using the census transform with a 48x48 pattern.

vc_corr_census_48x48() is a macro which calls vc_corr_census().

See also

vc_corr_census_pattern_init_48x48(), vc_corr_census_pattern_deinit_48x48().

vc_corr_census_pattern_init_32x32

#define vc_corr_census_pattern_init_32x32	(		pat,
			resultMaxNr,
			imgPat,
			imgMask,
			corrMinVal,
			distHor,
			distVer
	)		vc_corr_census_pattern_init(pat, resultMaxNr, imgPat, imgMask, corrMinVal, distHor, distVer, 32, 32, &FL_census32x32_32U32, &FL_hamming_32U32)

This macro is a convenience call for using the census transform with a 32x32 pattern.

vc_corr_census_pattern_init_32x32() is a macro which calls vc_corr_census_pattern_init().

See also

vc_corr_census_32x32(), vc_corr_census_pattern_deinit_32x32().

vc_corr_census_pattern_init_48x48

#define vc_corr_census_pattern_init_48x48	(		pat,
			resultMaxNr,
			imgPat,
			imgMask,
			corrMinVal,
			distHor,
			distVer
	)		vc_corr_census_pattern_init(pat, resultMaxNr, imgPat, imgMask, corrMinVal, distHor, distVer, 48, 48, &FL_census48x48_72U32, &FL_hamming_72U32)

This macro is a convenience call for using the census transform with a 48x48 pattern.

vc_corr_census_pattern_init_48x48() is a macro which calls vc_corr_census_pattern_init().

See also

vc_corr_census_48x48(), vc_corr_census_pattern_deinit_48x48().

vc_corr_census_pattern_deinit_32x32

#define vc_corr_census_pattern_deinit_32x32

(

pat

)

vc_corr_census_pattern_deinit(pat, 32, 32)

This macro is a convenience call for using the census transform with a 32x32 pattern.

vc_corr_census_pattern_deinit_32x32() is a macro which calls vc_corr_census_pattern_deinit().

See also

vc_corr_census_pattern_init_32x32(), vc_corr_census_32x32().

vc_corr_census_pattern_deinit_48x48

#define vc_corr_census_pattern_deinit_48x48

(

pat

)

vc_corr_census_pattern_deinit(pat, 48, 48)

This macro is a convenience call for using the census transform with a 48x48 pattern.

vc_corr_census_pattern_deinit_48x48() is a macro which calls vc_corr_census_pattern_deinit().

See also

vc_corr_census_pattern_init_48x48(), vc_corr_census_48x48().

Function Documentation

vc_corr_census()

I32 vc_corr_census	(	image *	Search,
		VCCorrCensusPattern *	pat,
		I32	patNr,
		I32	mustKx,
		I32	mustKy,
		void(*)(U32 pitch, U32 *sumX, U8 *src, U32 *dst)	fn_census_XU32,
		I32(*)(U32 *src1, U32 *src2)	fn_hamming_XU32
	)

This function searches a pattern defined by image Pattern in the Search image using census-transform correlation. The x- and y-position as well as the correlation value of the matches is available at the result struct at each pattern. You can optionally define a mask for each pattern, which says if a pixel position should be ignored or matched against the pattern grey value. It is faster to provide all patterns to one search run instead of doing several runs for each pattern.

This Correlation is done using pixel accuracy.

Please remember, the usage of pyramid() wrt. both the patterns and the search image speeds up correlations tremendously.

There are convenience macros available: vc_corr_census_32x32(), vc_corr_census_48x48().

An Example using the 48x48 macros:

#define PATTERNS (5)

image imgPat[PATTERNS]; //containing the pattern images.
VCCorrCensusPattern  pat[PATTERNS] = {NULL_VCCorrCensusPattern};

// ONCE, for example at program start, for setting up patterns
{
      for(a= 0; a< PATTERNS; a++)
            pat[a] = (VCCorrCensusPattern) NULL_VCCorrCensusPattern;

      for(a= 0; a< PATTERNS; a++)
      {
            rc =  vc_corr_census_pattern_init_48x48(&(pat[a]), RESULTS, &imgPat[a], NULL, 0, -1, -1);
            if(rc<0){ee=-1; goto fail;}
      }
}

// EVERY new imgSearch
{
      rc =  vc_corr_census_48x48(&imgSearch, pat, PATTERNS);
      if(rc<0){ee=-3+10*rc; goto fail;}

      for(a= 0; a< PATTERNS; a++)
      {
            for(i= 0; i< pat[a].result.nr; i++)
            {
                  printf("Pattern %2d, Result %2d:  pos(x,y): (%4d, %4d)  corr: %d/%d:%4.1f%%\n", a, i, pat[a].result.x[i], pat[a].result.y[i], pat[a].result.corr[i], pat[a].result.corrMaxVal, (pat[a].result.corr[i]*100.0)/pat[a].result.corrMaxVal);
            }
      }
}

// ONCE, for example at program end, for releasing patterns
{
      for(a= 0; a< PATTERNS; a++)
      {
            vc_corr_census_pattern_deinit_48x48(&pat[a]);
      }
}

Parameters

Search	The Image to be Searched In.
pat	An array of patterns to be searched, each pre-initialized with the corresponding vc_corr_census_pattern_init() function.
patNr	Number of patterns searched simultaneously (pat array size), not to be confused with result number defined at each pattern.
mustKx,mustKy	The search pattern image has to have the same dx or dy as this number.
fn_census_XU32	The function used to calculate the census transform.
fn_hamming_XU32	The function used to calculate the hamming distance.

See also

vc_corr_census_pattern_init(), vc_corr_census_pattern_deinit().

Return values

ERR_FORMAT	if Search->dx or Search->dy, or imgPat->dx or imgPat->dy are not in Range [0,65535].
ERR_FORMAT	if Search->dx < imgPat->dx or Search->dy < imgPat->dy.
ERR_FORMAT	if Search->dx * Search->dy >= 4096 * 4096.
ERR_FORMAT	if a pattern does not harmonize with mustKx or mustKy.
ERR_NONE	on Success.

vc_corr_census_pattern_init()

I32 vc_corr_census_pattern_init	(	VCCorrCensusPattern *	pat,
		I32	resultMaxNr,
		image *	imgPat,
		image *	imgMask,
		I32	corrMinVal,
		I32	distHor,
		I32	distVer,
		I32	mustKx,
		I32	mustKy,
		void(*)(U32 pitch, U32 *sumX, U8 *src, U32 *dst)	fn_census_XU32,
		I32(*)(U32 *src1, U32 *src2)	fn_hamming_XU32
	)

This function initializes a pattern defined by image imgPat for search with vc_corr_census(). Optionally set a mask (a grey value of 0 excludes the corresponding imgPat pixel from search), or set it to NULL for whole pattern image search. You can set a maximum result number for the pattern. The vc_corr_census() tries to fill it up regardless how bad the match is. You can give a minimum correlation value for possible speedup.

There are convenience macros available: vc_corr_census_pattern_init_32x32(), vc_corr_census_pattern_init_48x48().

Parameters

pat	The initialized pattern for usage at the corresponding vc_corr_census() function.
resultMaxNr	Maximum match number for the pattern.
imgPat	The pattern image (dx/dy must correspond to mustKx and mustKy. Currently only 48x48 and 32x32 are supported).
imgMask	A pixel value of 0 excludes Pixels at Pattern from usage, set to NULL for 'use all Reference Pattern Pixels'
corrMinVal	set to 0 to get most matches, raise for possible speed up.
distHor,distVer	minimum distance between different results.
mustKx,mustKy	The search pattern image has to have the same dx or dy as this number.
fn_census_XU32	The function used to calculate the census transform.
fn_hamming_XU32	The function used to calculate the hamming distance.

See also

vc_corr_census_pattern_deinit(), vc_corr_census().

vc_corr_census_pattern_deinit()

I32 vc_corr_census_pattern_deinit	(	VCCorrCensusPattern *	pat,
		I32	mustKx,
		I32	mustKy
	)

This function deinitializes a pattern initialized with vc_corr_census_pattern_init().

There are convenience macros available: vc_corr_census_pattern_deinit_32x32(), vc_corr_census_pattern_deinit_48x48().

See also

vc_corr_census_pattern_init(), vc_corr_census().