Minos (MinosCVC.dll) 15.0
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]ImageHandle of the image to be processed.
[in]TemplateHandle 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]IndexImagePlane 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]IndexTemplatePlane 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]DensityScan 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]AreaArea of interest.
[in]SubPixelWhen 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]OptCorCorrelation value of the best result.
[out]XX-position corresponding to the highest correlation result.
[out]YY-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]ImageHandle of the image to be processed.
[in]TemplateHandle 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]IndexImagePlane 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]IndexTemplatePlane 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]DensityScan 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]AreaArea of interest.
[in]AThresholdDefines the minimum correlation a result must have with the Template for the result to be added to the Results list.
[in]ARadiusMinimum 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]AMaxSearchMaximum number of results to be returned.
[in]FProgressPointer 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]PProgressPointer to user-defined data that will be passed on to the FProgress function.
[out]ResultsReceives 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;
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.
Definition: MinosCorrelationExport.cpp:313
void * RESULTS
Handle to a list of Minos search results.
Definition: iMinosCVC.h:64
cvbbool_t SearchResult(RESULTS handle, cvbdim_t index, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName, cvbval_t &searchID)
This function reads an entry from a list of search results.
Definition: MinosSearchExport.cpp:165
cvbval_t SearchResultsCount(RESULTS handle)
Returns the number of entries in a RESULTS list.
Definition: MinosSearchExport.cpp:110