Correlation Functions

Functions
cvbbool_t	OptCorrelation (IMG Image, IMG Template, cvbdim_t IndexImage, cvbdim_t IndexTemplate, cvbdensity_t Density, TArea Area, cvbbool_t SubPixel, double &OptCor, double &X, double &Y)
	Find the best match for a correlation template in an image. More...
cvbbool_t	OptCorrelations (IMG Image, IMG Template, cvbdim_t IndexImage, cvbdim_t IndexTemplate, cvbdensity_t Density, TArea Area, double AThreshold, cvbdim_t ARadius, cvbval_t AMaxSearch, TFCallbackScan FProgress, void *PProgress, RESULTS &Results)
	Find all correlation matches for a correlation template in an image. More...

Detailed Description

Function Documentation

OptCorrelation()

cvbbool_t OptCorrelation	(	IMG	Image,
		IMG	Template,
		cvbdim_t	IndexImage,
		cvbdim_t	IndexTemplate,
		cvbdensity_t	Density,
		TArea	Area,
		cvbbool_t	SubPixel,
		double &	OptCor,
		double &	X,
		double &	Y
	)

Find the best match for a correlation template in an image.

This function slides the template over the Image in such manner that the correlation template's origin assumes all possible positions in the specified search area, calculating the normalized gray scale correlation as it goes. The correlation value and location of the highest correspondence between and image location and the correlation template is returned as the result.

Parameters

[in]	Image	Handle of the image to be processed.
[in]	Template	Handle of the template for which to search in the Image. The correlation template is just another Common Vision Blox image. The coordinate system's origin on that image defines the anchor position for the recognition. Make sure that the template image's coordinate system has been set properly before passing the image to this function.
[in]	IndexImage	Plane of the Image to be processed. Passing -1 here will make Minos calculate the correlation over all available image plane (at increased processing times).
[in]	IndexTemplate	Plane of the Template to be processed. Passing -1 here will make Minos calculate the correlation over all available image plane (at increased processing times).
[in]	Density	Scan density to apply when searching for the best correlation match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also deteriorating the search results). Note that this scan density does not only apply to the sliding of the template over the area of interest, but also to the calculation of the normalized gray scale correlation itself!
[in]	Area	Area of interest.
[in]	SubPixel	When set to true, the optimum result will be reported at sub pixel accuracy by carrying out the following additional calculations: If the Density was lower than 1000 the position of the maximum is first refined to within 1 pixel, eliminating part of the detrimental effect of the reduced scan density. Then a quadratic to the correlation values in a 3x3 environment around the best result is calculated in order to provide a sub pixel estimation of the pattern position.
[out]	OptCor	Correlation value of the best result.
[out]	X	X-position corresponding to the highest correlation result.
[out]	Y	Y-position corresponding to the highest correlation result.

Returns

TRUE on success, FALSE if any error occurs. Possible reasons are:

• Invalid handles for Image and/or Template
• Invalid plane indices specified for Image and/or Template
• Image and/or Template has more than 8 bits per pixel

See also

OptCorrelations

OptCorrelations()

cvbbool_t OptCorrelations	(	IMG	Image,
		IMG	Template,
		cvbdim_t	IndexImage,
		cvbdim_t	IndexTemplate,
		cvbdensity_t	Density,
		TArea	Area,
		double	AThreshold,
		cvbdim_t	ARadius,
		cvbval_t	AMaxSearch,
		TFCallbackScan	FProgress,
		void *	PProgress,
		RESULTS &	Results
	)

Find all correlation matches for a correlation template in an image.

This function slides the template over the Image in such manner that the correlation template's origin assumes all possible positions in the specified search area, calculating the normalized gray scale correlation as it goes. Where the correlation value exceeds the specified threshold, the correlation value and its corresponding location are added to a list of results that is returned at the end of the calculations.

Parameters

[in]	Image	Handle of the image to be processed.
[in]	Template	Handle of the template for which to search in the Image. The correlation template is just another Common Vision Blox image. The coordinate system's origin on that image defines the anchor position for the recognition. Make sure that the template image's coordinate system has been set properly before passing the image to this function.
[in]	IndexImage	Plane of the Image to be processed. Passing -1 here will make Minos calculate the correlation over all available image plane (at increased processing times).
[in]	IndexTemplate	Plane of the Template to be processed. Passing -1 here will make Minos calculate the correlation over all available image plane (at increased processing times).
[in]	Density	Scan density to apply when searching for the best correlation match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also deteriorating the search results). Note that this scan density does not only apply to the sliding of the template over the area of interest, but also to the calculation of the normalized gray scale correlation itself!
[in]	Area	Area of interest.
[in]	AThreshold	Defines the minimum correlation a result must have with the Template for the result to be added to the Results list.
[in]	ARadius	Minimum distance between two results in the Results list. At the end of the correlation search the result list is searched for result pairs violating this minimum distance criterion; from the offending pairs the result with the lower quality will be removed from Results.
[in]	AMaxSearch	Maximum number of results to be returned.
[in]	FProgress	Pointer to a callback that is to be used for error reporting. This callback will be called at the end of every scan line, giving the callee an opportunity to interrupt the current scan. I no interruption or progress report are required simply pass a nullptr here.
[in]	PProgress	Pointer to user-defined data that will be passed on to the FProgress function.
[out]	Results	Receives the handle to a list of correlation results that exceeded the specified AThreshold value. This list may then be processed with the functions SearchResultsCount, SearchResult as well as SortResultsByPosition and SortResultsByQuality. Remember to dispose of the Results object by calling ReleaseObject from the CVCImg.dll once it is no longer needed.

Returns

TRUE on success, FALSE if any error occurs. Possible reasons are:

• Invalid handles for Image and/or Template
• Invalid plane indices specified for Image and/or Template
• Image and/or Template has more than 8 bits per pixel

See also

OptCorrelation, SearchResultsCount, SearchResult, SortResultsByPosition, SortResultsByQuality

Example

Iterate over all results returned by OptCorrelations

// assumptions:
// - tpl refers to a valid image
// - img refers to a valid image that contains zero or more instances
//       of the object visible in tpl
// - tpl and img are compatible and both have 8 bits per component
RESULTS results = nullptr;
TArea aoi;
MaxImageArea(img, aoi); // scan entire image
if (OptCorrelations(img, tpl, -1, -1, 1000, aoi, 0.6,
  std::min<cvbdim_t>(ImageWidth(tpl), ImageHeight(tpl)), 1000
  nullptr, nullptr, results))
{
  auto numResults = SearchResultsCount(results);
  for (int i = 0; i < numResults; ++i)
  {
    double xPos, yPos, quality, dx, dy;
    xPos = yPos = quality = dx = dy = 0.0;
    long id = 0;
    char* classname = nullptr;
    SearchResult(results, i,
      quality, xPos, yPos, dx, dy, classname, id);
    // hints: classname is always '?' for correlation results but
    //        a variable has to be passed anyway; 
    //        likewise id is always 0 for correlation results
    std::cout << "result #" << i << ": x = " << xPos << ", y = " << yPos;
    std::cout << ", q = " << quality << std::endl;
  }
  ReleaseObject(results);
}
else
  std::cout << "OptCorrelations() call failed." << std::endl;