ShapeFinder (SF.dll) 15.0
ShapeFinder2 Functions

Functions

SF CreateSF2 (IMG Image, cvbdim_t Index, cvbdim_t MX, cvbdim_t MY, double MAlpha, double MScale, cvbdim_t FWL, cvbdim_t FWT, cvbdim_t FWR, cvbdim_t FWB, cvbdim_t Threshold, cvbdim_t MinFeatureNumber, TSymmetryParams SParams, PIXELLIST DontCareList)
 Creates a ShapeFinder2 model from the input data. More...
 
SF CreateSF2Ex (IMG Image, cvbdim_t Index, cvbdim_t MX, cvbdim_t MY, double MAlpha, double MScale, cvbdim_t FWL, cvbdim_t FWT, cvbdim_t FWR, cvbdim_t FWB, cvbval_t Threshold, cvbval_t MinFeatureNumber, cvbval_t MaxCoarseScale, TSymmetryParams SParams, PIXELLIST DontCareList)
 Creates a ShapeFinder2 model from the input data. More...
 
SF CreateSF2ExEx (IMG Image, cvbdim_t Index, cvbdim_t MX, cvbdim_t MY, double MAlpha, double MScale, cvbdim_t FWL, cvbdim_t FWT, cvbdim_t FWR, cvbdim_t FWB, cvbval_t Threshold, cvbval_t MinFeatureNumber, cvbval_t MaxCoarseScale, TSymmetryParams SParams, PIXELLIST DontCareList, int GradientMode, int AProfileSize, double ADelta)
 Creates a ShapeFinder2 model from the input data. More...
 
cvbbool_t GetSF2EdgeImage (IMG Image, cvbdim_t Index, IMG &ImgOut)
 Creates a Sobel-filtered image that shows what ShapeFinder2 will use as the basis for feature extraction during model generation. More...
 
cvbbool_t GetSF2Features (SF sf, PIXELLIST &FineFeatures, PIXELLIST &CoarseFeatures, cvbval_t &CoarseScale)
 Returns the list of coarse and fine features of a ShapeFinder2 model. More...
 
cvbbool_t GetSF2SearchAllPars (SF sf, TSearchAllParams &SearchAllPars)
 Queries the currently set parameters that control the generation of a list of solutions during a ShapeFinder2 search operation. More...
 
cvbbool_t GetSF2Symmetries (SF sf, TSymmetryParams &SymmetryParams)
 Returns the symmetry parameters with which the specified ShapeFinder2 model has been generated. More...
 
cvbbool_t GetSF2TrainingWindow (SF sf, cvbdim_t &TWL, cvbdim_t &TWT, cvbdim_t &TWR, cvbdim_t &TWB)
 Returns the feature window that was specified during the creation of a ShapeFinder2 model. More...
 
cvbbool_t SetSF2SearchAllPars (SF sf, TSearchAllParams SearchAllPars)
 Sets the parameters that control the generation of a list of solutions during a ShapeFinder2 search operation. More...
 
cvbbool_t SF2Search (SF sf, IMG Image, cvbdim_t Index, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, PIXELLIST &Solutions)
 Use a ShapeFinder2 model for finding occurrences of the trained pattern in an image. More...
 
cvbbool_t SF2SearchEx (SF sf, IMG Image, cvbdim_t Index, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, TSymmetryParams Limits, PIXELLIST &Solutions)
 Use a ShapeFinder2 model for finding occurrences of the trained pattern in an image. More...
 
cvbbool_t SF2UseCuda (SF Sf, SF2CudaStatus Override)
 Allows disabling the use of CUDA and returns whether CUDA will in fact be used. More...
 

Detailed Description

Function Documentation

◆ CreateSF2()

SF CreateSF2 ( IMG  Image,
cvbdim_t  Index,
cvbdim_t  MX,
cvbdim_t  MY,
double  MAlpha,
double  MScale,
cvbdim_t  FWL,
cvbdim_t  FWT,
cvbdim_t  FWR,
cvbdim_t  FWB,
cvbdim_t  Threshold,
cvbdim_t  MinFeatureNumber,
TSymmetryParams  SParams,
PIXELLIST  DontCareList 
)

Creates a ShapeFinder2 model from the input data.

If successful, the resulting ShapeFinder2 model may afterwards be used with any function that is able to work on a ShapeFinder2 model. Remember to call ReleaseObject from the CVCImg.dll on the model once it is no longer needed.

Parameters
[in]ImageHandle to the image containing the data from which to train the model.
[in]IndexColor plane from which to train the model.
[in]MXX-position in the Image from which to train the model.
[in]MYY-position in the Image from which to train the model.
[in]MAlphaRotation at which the object to be trained is shown in the Image at position (MX, MY). This angle will be used as an offset for the results in all subsequent search calls.
[in]MScaleScale at which the object to be traines id shown in in the Image at position (MX, MY). This scale will be applied as a factor to the results in all subsequent search calls.
[in]FWLLeft extent of the feature window for training (relative to MX - typically a negative value).
[in]FWTTop extent of the feature window for training (relative to MY - typically a negative value).
[in]FWRRight extent of the feature window for training (relative to MX).
[in]FWBBottom extent of the feature window for training (relative to MY).
[in]ThresholdThreshold for the gradient slope to be used in training (see Counting Contrasts). Only gradients equal to or higher than this threshold will become model features. The threshold passed here will become a property of the classifier that will also be applied when using the classifier for searching in an image (use the SetSFThreshold function to alter it if necessary).
[in]MinFeatureNumberMinimum number of features to be extracted from the image. This also influences the resolution of the coarse scale image (the coarse scale image uses the largest scale at which the required number of features still exists in the coarse image).
[in]SParamsSymmetry parameter for the model generation. See TSymmetryParams for detailed information. SP_SimpleModel, SP_TolerantModel, SP_RotationInvariance, SP_ScaleInvariance and SP_FullInvariance provide useful default values here.
[in]DontCareListA PIXELLIST (see CVCImg.dll documentation) of image coordinates relative to MX and MY, which must not be used as features.
Returns
If the tool was able to generate a ShapeFinder2 model a pointer to the newly created model will be returned. Otherwise a nullptr will be returned. Remember to call ReleaseObject from the CVCImg.dll on the returned handle once it is no longer needed.
See also
SF2Search, SF2SearchEx, CreateSF2Ex, CreateSF2ExEx, TSymmetryParams
Examples
Delphi ShapeFinder2 Example
VC ShapeFinder2 Example
VB.NET ShapeFinder2 Teach Example

◆ CreateSF2Ex()

SF CreateSF2Ex ( IMG  Image,
cvbdim_t  Index,
cvbdim_t  MX,
cvbdim_t  MY,
double  MAlpha,
double  MScale,
cvbdim_t  FWL,
cvbdim_t  FWT,
cvbdim_t  FWR,
cvbdim_t  FWB,
cvbval_t  Threshold,
cvbval_t  MinFeatureNumber,
cvbval_t  MaxCoarseScale,
TSymmetryParams  SParams,
PIXELLIST  DontCareList 
)

Creates a ShapeFinder2 model from the input data.

If successful, the resulting ShapeFinder2 model may afterwards be used with any function that is able to work on a ShapeFinder2 model. Remember to call ReleaseObject from the CVCImg.dll on the model once it is no longer needed.

The difference between CreateSF2Ex and its sibling CreateSF2 is that with CreateSF2Ex it is possible to specify an upper limit to the scale factor of the coarse features. When using a low MinFeatureNumber and/or working with a combination of Image and Threshold that yields a very high number of features, the automatic approach that CreateSF2 is using may lead to very high scale factors between the image and the coarse feature layer. Very high scale factors, however, are usually not beneficial for object detection (which starts in the coarse layer). The only way to reduce the coarse layer scale with CreateSF2 is to increase MinFeatureNumber - however that will have a negative impact on the processing time. With CreateSF2Ex the same effect may be achieved without any negative consequences for processing time by choosing the value for MaxCoarseScale appropriately.

Parameters
[in]ImageHandle to the image containing the data from which to train the model.
[in]IndexColor plane from which to train the model.
[in]MXX-position in the Image from which to train the model.
[in]MYY-position in the Image from which to train the model.
[in]MAlphaRotation at which the object to be trained is shown in the Image at position (MX, MY). This angle will be used as an offset for the results in all subsequent search calls.
[in]MScaleScale at which the object to be trained is shown in in the Image at position (MX, MY). This scale will be applied as a factor to the results in all subsequent search calls.
[in]FWLLeft extent of the feature window for training (relative to MX - typically a negative value).
[in]FWTTop extent of the feature window for training (relative to MY - typically a negative value).
[in]FWRRight extent of the feature window for training (relative to MX).
[in]FWBBottom extent of the feature window for training (relative to MY).
[in]ThresholdThreshold for the gradient slope to be used in training (see Counting Contrasts). Only gradients equal to or higher than this threshold will become model features. The threshold passed here will become a property of the classifier that will also be applied when using the classifier for searching in an image (use the SetSFThreshold function to alter it if necessary).
[in]MinFeatureNumberMinimum number of features to be extracted from the image. This also influences the resolution of the coarse scale image (the coarse scale image uses the largest scale at which the required number of features still exists in the coarse image).
[in]MaxCoarseScaleSpecifies the upper limit to the coarse layer zoom factor. Note that MaxCoarseScale is given as the exponent to the base 2, which means that e.g. a value of MaxCoarseScale = 3 will limit the zoom factor to 2^3 = 8.
[in]SParamsSymmetry parameter for the model generation. See TSymmetryParams for detailed information. SP_SimpleModel, SP_TolerantModel, SP_RotationInvariance, SP_ScaleInvariance and SP_FullInvariance provide useful default values here.
[in]DontCareListA PIXELLIST (see CVCImg.dll documentation) of image coordinates relative to MX and MY, which must not be used as features.
Returns
If the tool was able to generate a ShapeFinder2 model a pointer to the newly created model will be returned. Otherwise a nullptr will be returned. Remember to call ReleaseObject from the CVCImg.dll on the returned handle once it is no longer needed.
See also
SF2Search, SF2SearchEx, CreateSF2, CreateSF2ExEx, TSymmetryParams
Examples
Delphi ShapeFinder2 Example
VC ShapeFinder2 Example
VB.NET ShapeFinder2 Teach Example

◆ CreateSF2ExEx()

SF CreateSF2ExEx ( IMG  Image,
cvbdim_t  Index,
cvbdim_t  MX,
cvbdim_t  MY,
double  MAlpha,
double  MScale,
cvbdim_t  FWL,
cvbdim_t  FWT,
cvbdim_t  FWR,
cvbdim_t  FWB,
cvbval_t  Threshold,
cvbval_t  MinFeatureNumber,
cvbval_t  MaxCoarseScale,
TSymmetryParams  SParams,
PIXELLIST  DontCareList,
int  GradientMode,
int  AProfileSize,
double  ADelta 
)

Creates a ShapeFinder2 model from the input data.

If successful, the resulting ShapeFinder2 model may afterwards be used with any function that is able to work on a ShapeFinder2 model. Remember to call ReleaseObject from the CVCImg.dll on the model once it is no longer needed.

The difference between CreateSF2ExEx and its sibling CreateSF2Ex is that CreateSF2ExEx is capable of generating ShapeFinder2 models that use a so-called profile mode. The profile mode is useful where the geometrical arrangement of the model's features alone is not sufficient to ensure a precise localization and scale/orientation measurement of an object. Imagine, for example, a set of features that are arrange on an (almost) straight line: Localization of the object in the direction perpendicular to the line is easily possible, but a high uncertainty in the lateral direction remains. This problem can in many cases be addressed by using not only single feature points, but gray value profiles extracted along the direction of the feature's gradient. In the above example: By not only using the feature points on the line, but also taking into account the gray values of a few pixels above and below the line localization in the lateral direction may be improved greatly.

Parameters
[in]ImageHandle to the image containing the data from which to train the model.
[in]IndexColor plane from which to train the model.
[in]MXX-position in the Image from which to train the model.
[in]MYY-position in the Image from which to train the model.
[in]MAlphaRotation at which the object to be trained is shown in the Image at position (MX, MY). This angle will be used as an offset for the results in all subsequent search calls.
[in]MScaleScale at which the object to be trained is shown in in the Image at position (MX, MY). This scale will be applied as a factor to the results in all subsequent search calls.
[in]FWLLeft extent of the feature window for training (relative to MX - typically a negative value).
[in]FWTTop extent of the feature window for training (relative to MY - typically a negative value).
[in]FWRRight extent of the feature window for training (relative to MX).
[in]FWBBottom extent of the feature window for training (relative to MY).
[in]ThresholdThreshold for the gradient slope to be used in training (see Counting Contrasts). Only gradients equal to or higher than this threshold will become model features. The threshold passed here will become a property of the classifier that will also be applied when using the classifier for searching in an image (use the SetSFThreshold function to alter it if necessary).
[in]MinFeatureNumberMinimum number of features to be extracted from the image. This also influences the resolution of the coarse scale image (the coarse scale image uses the largest scale at which the required number of features still exists in the coarse image).
[in]MaxCoarseScaleSpecifies the upper limit to the coarse layer zoom factor. Note that MaxCoarseScale is given as the exponent to the base 2, which means that e.g. a value of MaxCoarseScale = 3 will limit the zoom factor to 2^3 = 8.
[in]SParamsSymmetry parameter for the model generation. See TSymmetryParams for detailed information. SP_SimpleModel, SP_TolerantModel, SP_RotationInvariance, SP_ScaleInvariance and SP_FullInvariance provide useful default values here.
[in]DontCareListA PIXELLIST (see CVCImg.dll documentation) of image coordinates relative to MX and MY, which must not be used as features.
[in]GradientModeSpecify 1 here to make use of the gradient mode described earlier, 0 to use the regular mode (in this case the resulting ShapeFinder2 model will be the same as if it had been created CreateSF2Ex).
[in]AProfileSizeNumber of points to use for the gradient profiles in the ShapeFinder2 model. Please always provide an odd number here. Keep in mind that increasing this value will greatly boost the number of pixels that will require processing in ShapeFinder2's correlation stage and that therefore higher values for ProfileSize will lead to an increase in processing time.
[in]ADeltaSpacing between the points of a profile in pixels.
Returns
If the tool was able to generate a ShapeFinder2 model a pointer to the newly created model will be returned. Otherwise a nullptr will be returned. Remember to call ReleaseObject from the CVCImg.dll on the returned handle once it is no longer needed.
See also
SF2Search, SF2SearchEx, CreateSF2, CreateSF2Ex, TSymmetryParams
Examples
Delphi ShapeFinder2 Example
VC ShapeFinder2 Example
VB.NET ShapeFinder2 Teach Example

◆ GetSF2EdgeImage()

cvbbool_t GetSF2EdgeImage ( IMG  Image,
cvbdim_t  Index,
IMG &  ImgOut 
)

Creates a Sobel-filtered image that shows what ShapeFinder2 will use as the basis for feature extraction during model generation.

With this image it is easy to visualize the effect of different gradient slope threshold settings: Simply set the image into a display control and set the DisplayGain property to 255 and the threshold to be visualized to DisplayOffset. The display will then show black pixels where the gradient slope is below the threshold and white pixels where the gradient slop exceeds the threshold (in other words: white pixels are potential feature locations).

Remember to call ReleaseObject from the CVCImg.dll once the output image (ImgOut) is no longer needed.

Usage example:

bool ShowFeatureImage(CCvdisplayctrl display, IMG img, int fwl, int fwt, int fwr, int fwb, int threshold)
{
if (!IsImage(img))
return false;
IMG featureWindow = nullptr;
CreateImageMap(img, fwl, fwt, fwr, fwb, fwr - fwl + 1, fwb - fwt + 1, featureWindow);
if (IsImage(featureWindow))
{
IMG sobel = nullptr;
GetSF2EdgeImage(featureWindow, 0, sobel);
ReleaseObject(featureWindow);
display.SetImage(reinterpret_cast<intptr_t>(sobel);
ReleaseObject(sobel);
display.SetDisplayGain(255.0);
display.SetDisplayOffset(threshold);
}
}
cvbbool_t GetSF2EdgeImage(IMG Image, cvbdim_t Index, IMG &ImgOut)
Creates a Sobel-filtered image that shows what ShapeFinder2 will use as the basis for feature extract...
Definition: FromDelphi_USF.cpp:3478
Parameters
[in]ImageHandle to the source image.
[in]IndexPlane of the Image to be processed.
[out]ImgOutReceives the handle to the sobel-filtered image.
Returns
TRUE if the image was successfully filtered, FALSE otherwise.
Examples
VB.NET ShapeFinder2 Teach Example

◆ GetSF2Features()

cvbbool_t GetSF2Features ( SF  sf,
PIXELLIST &  FineFeatures,
PIXELLIST &  CoarseFeatures,
cvbval_t &  CoarseScale 
)

Returns the list of coarse and fine features of a ShapeFinder2 model.

Feature positions will be returned to the caller as 3-dimensional PIXELLIST objects (components 0 and 1 hold the x and y position, component 3 is to be ignored) relative to the ShapeFinder2 model's center position (i.e. x and y positions of the feature may be negative).

Parameters
[in]sfHandle to the ShapeFinder2 model to be queried.
[out]FineFeaturesThree-component PIXELLIST with the positions (x, y) of the fine-scale features potentially used in the final search phase of ShapeFinder2 (see Generalized Positions and Search, Final Phase; 3rd component of the PIXELLIST is to be ignored). Remember to call ReleaseObject from the CVCImg.dll once this PIXELLIST is no longer needed.
[out]CoarseFeaturesThree-component PIXELLIST with the positions (x, y) of the coarse-scale features potentially used in the final search phase of ShapeFinder2 (see Generalized Positions and Search, Final Phase; 3rd component of the PIXELLIST is to be ignored). Remember to call ReleaseObject from the CVCImg.dll once this PIXELLIST is no longer needed.
[out]CoarseScaleScale factor between the coarse-scale features and the fine-scale features.
Returns
TRUE if it was possible to retrieve the lists, FALSE if sf does not refer to a valid ShapeFinder2 classifier or if at least one of the feature lists is empty or if the PIXELLIST creation failed.
See also
Preliminary Search
Examples
VB.NET ShapeFinder2 Teach Example

◆ GetSF2SearchAllPars()

cvbbool_t GetSF2SearchAllPars ( SF  sf,
TSearchAllParams SearchAllPars 
)

Queries the currently set parameters that control the generation of a list of solutions during a ShapeFinder2 search operation.

See the description of TSearchAllParams for details about how the members of that struct will be used when searching for an object.

Parameters
[in]sfHandle to the ShapeFinder2 model to be queried.
[out]SearchAllParsCurrent search parameters. See TSearchAllParams for more information.
Returns
TRUE if the parameters were successfully queried, FALSE if sf does not refer to a valid ShapeFinder2 model.
See also
Preliminary Search, TSearchAllParams, TSearchAllParams

◆ GetSF2Symmetries()

cvbbool_t GetSF2Symmetries ( SF  sf,
TSymmetryParams SymmetryParams 
)

Returns the symmetry parameters with which the specified ShapeFinder2 model has been generated.

The symmetry parameters are fixed after the creation of a ShapeFinder2 model and cannot be changed later on. They define the rotation and scale range that a ShapeFinder2 model may cover. See also TSymmetryParams.

Parameters
[in]sfHandle to the ShapeFinder2 model to be queried.
[out]SymmetryParamsSymmetry parameters of the model.
Returns
TRUE if the symmetry parameters were retrieved, FALSE if the sf handle does not refer to a valid ShapeFinder2 model (in this case the parameters SymmetryParams has not been altered).
See also
TSymmetryParams, TSymmetryParams
Examples
VB.NET ShapeFinder2 Teach Example

◆ GetSF2TrainingWindow()

cvbbool_t GetSF2TrainingWindow ( SF  sf,
cvbdim_t &  TWL,
cvbdim_t &  TWT,
cvbdim_t &  TWR,
cvbdim_t &  TWB 
)

Returns the feature window that was specified during the creation of a ShapeFinder2 model.

The feature window that was specified during the creation of a ShapeFinder2 model (named 'training window' here) may easily differ from the model's actual feature window as returned by GetSFFeatureWindow: The feature windows is usually at least slightly smaller than the training window. Nevertheless the training window may be usedful for display purposes and is therefore preserved as a property of each ShapeFinder2 model.

Parameters
[in]sfHandle to the ShapeFinder2 model to be queried.
[out]TWLLeft edge of the training window relative to the model origin (typically a negative value).
[out]TWTTop edge of the training window relative to the model origin (typically a negative value).
[out]TWRRight edge of the training window relative to the model origin.
[out]TWBBottom edge of the training window relative to the model origin.
Returns
TRUE if the training window was queried successfully, FALSE if sf does not refer to a valid ShapeFinder2 model (in this case the parameters TLW, TWT, TWR and TWB will not be modified).
See also
CreateSF2, CreateSF2Ex, CreateSF2ExEx
Examples
VB.NET ShapeFinder2 Teach Example

◆ SetSF2SearchAllPars()

cvbbool_t SetSF2SearchAllPars ( SF  sf,
TSearchAllParams  SearchAllPars 
)

Sets the parameters that control the generation of a list of solutions during a ShapeFinder2 search operation.

See the description of TSearchAllParams for details about how the members of that struct will be used when searching for an object.

Parameters
[in]sfHandle to the ShapeFinder2 model on which to set the search parameters.
[in]SearchAllParsSearch parameters to be set. See the description of TSearchAllParams for more information.
Returns
TRUE if the parameters have been set, FALSE if sf does not refer to a valid ShapeFinder2 model.
See also
Preliminary Search, TSearchAllParams, TSearchAllParams
Examples
Delphi ShapeFinder2 Example
VC ShapeFinder2 Example
VB.NET ShapeFinder2 Teach Example

◆ SF2Search()

cvbbool_t SF2Search ( SF  sf,
IMG  Image,
cvbdim_t  Index,
cvbdim_t  Left,
cvbdim_t  Top,
cvbdim_t  Right,
cvbdim_t  Bottom,
PIXELLIST &  Solutions 
)

Use a ShapeFinder2 model for finding occurrences of the trained pattern in an image.

A search with a ShapeFinder2 model can be broken down into different stages. At the first stage, a search similar to what SFSearch does for ShapeFinder models is carried out. Then the resulting accumulator (which in this case is only used internally but not returned to the caller) is being analyzed for potential results using the approach described in the documentation of the TSearchAllParams structure. Finally - depending on the Precision member of the currently set TSearchAllParams parameter set - a correlation and hill-climbing step may be carried out at either coarse or fine scale.

Attention
When using one of the search functions of ShapeFinder (SFSearch, SF2Search, SF2SearchEx) in multiple threads simultaneously you must make sure that each thread is using its own copy of the ShapeFinder/ShapeFinder2 model! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The function CreateDuplicateSF may be used to create clones of any ShapeFinder/ShapeFinder2 model.
Parameters
[in]sfHandle to the ShapeFinder2 model to be used for searching.
[in]ImageHandle to the image in which to look for the patterns trained into the ShapeFinder2 model sf.
[in]IndexPlane in Image to be searched.
[in]LeftLeft coordinate of the search area in the image (in pixel coordinates).
[in]TopTop coordinate of the search area in the image (in pixel coordinates).
[in]RightRight coordinate of the search area in the image (in pixel coordinates).
[in]BottomBottom coordinate of the search area in the image (in pixel coordinates).
[out]SolutionsPIXELLIST object containing the the following information about the search results:
Dimension Content
0 x coordinate of the result position
1 y coordinate of the result position
2 quality of the result (depending on the Precision member of the currently used TSearchAllParams structure this is either a count of corresponding features or a correlation coefficient)
3 rotation of the result in degrees
4 scale factor of the result
See the description of the TSFSolution structure for an example how to access these results easily. Remember to call ReleaseObject from the CVCImg.dll on the returned PIXELLIST handle once it is no longer needed.
Returns
TRUE if the search was successful, FALSE otherwise. Note that even though the result is TRUE an empty PIXELLIST may be returned (and will have to be release with ReleaseObject).
See also
SF2SearchEx, TSearchAllParams, TSFSolution SetSF2SearchAllPars, GetSF2SearchAllPars, Generalized Positions and Search, Preliminary Search, Second Phase of SF2Search, Final Phase, TSearchAllParams, TSFSolution
Examples
ShapeFinder 2 Teach program

◆ SF2SearchEx()

cvbbool_t SF2SearchEx ( SF  sf,
IMG  Image,
cvbdim_t  Index,
cvbdim_t  Left,
cvbdim_t  Top,
cvbdim_t  Right,
cvbdim_t  Bottom,
TSymmetryParams  Limits,
PIXELLIST &  Solutions 
)

Use a ShapeFinder2 model for finding occurrences of the trained pattern in an image.

A search with a ShapeFinder2 model can be broken down into different stages. At the first stage, a search similar to what SFSearch does for ShapeFinder models is carried out. Then the resulting accumulator (which in this case is only used internally but not returned to the caller) is being analyzed for potential results using the approach described in the documentation of the TSearchAllParams structure. Finally - depending on the Precision member of the currently set TSearchAllParams parameter set - a correlation and hill-climbing step may be carried out at either coarse or fine scale.

In addition to what its sibling SF2Search does, SF2SearchEx accepts an additional parameter that defines the limits for rotation and scale within which the results will be accepted. Any results that have a scale or rotation that exceeds the specified limits will be omitted.

Note that the limits may not be chosen arbitrarily:

  • Limits.A1 - Limits.A0| >= 10
  • Limits.R1 - Limits.R0 >= 0.09
Attention
When using one of the search functions of ShapeFinder (SFSearch, SF2Search, SF2SearchEx) in multiple threads simultaneously you must make sure that each thread is using its own copy of the ShapeFinder/ShapeFinder2 model! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The function CreateDuplicateSF may be used to create clones of any ShapeFinder/ShapeFinder2 model.
Parameters
[in]sfHandle to the ShapeFinder2 model to be used for searching.
[in]ImageHandle to the image in which to look for the patterns trained into the ShapeFinder2 model sf.
[in]IndexPlane in Image to be searched.
[in]LeftLeft coordinate of the search area in the image (in pixel coordinates).
[in]TopTop coordinate of the search area in the image (in pixel coordinates).
[in]RightRight coordinate of the search area in the image (in pixel coordinates).
[in]BottomBottom coordinate of the search area in the image (in pixel coordinates).
[in]LimitsRotation and scale limits to be applied when looking for matching objects (as a TSymmetryParams structure).
[out]SolutionsPIXELLIST object containing the the following information about the search results:
Dimension Content
0 x coordinate of the result position
1 y coordinate of the result position
2 quality of the result (depending on the Precision member of the currently used TSearchAllParams structure this is either a count of corresponding features or a correlation coefficient)
3 rotation of the result in degrees
4 scale factor of the result
See the description of the TSFSolution structure for an example how to access these results easily. Remember to call ReleaseObject from the CVCImg.dll on the returned PIXELLIST handle once it is no longer needed.
Returns
TRUE if the search was successful, FALSE otherwise. Note that even though the result is TRUE an empty PIXELLIST may be returned (and will have to be release with ReleaseObject).
See also
SF2SearchEx, TSearchAllParams, TSFSolution SetSF2SearchAllPars, GetSF2SearchAllPars, Generalized Positions and Search, Preliminary Search, Second Phase of SF2Search, Final Phase, TSymmetryParams, TSearchAllParams, TSFSolution
Examples
Delphi ShapeFinder2 Example
VC ShapeFinder2 Example
VB.NET ShapeFinder2 Teach Example

◆ SF2UseCuda()

cvbbool_t SF2UseCuda ( SF  Sf,
SF2CudaStatus  Override 
)

Allows disabling the use of CUDA and returns whether CUDA will in fact be used.

Parameters
[in]SfHandle to the ShapeFinder2 model to be used for searching.
[in]OverrideIf SF2CudaStatus::SFCS_ForceDisable CUDA won't be used in SF2Search.
Returns
true if Override == SFCS_Default and a CUDA capable device is present, false otherwise.
See also
SF2Search