ShapeFinder (SF.dll) 14.0
ShapeFinder Functions

Functions

SF ConcatenateSF (SF sf1, SF sf2)
 Creates a ShapeFinder model by concatenating the feature lists of the two input models. More...
 
SF CreateContrastReversedSF (SF sf)
 Creates a ShapeFinder model by reversing the contrasts of the input model. More...
 
SF CreateDuplicateSF (SF sf)
 Creates a copy of a ShapeFinder model. More...
 
SF CreateRSymmetricSF (SF sf, double Alpha0, double Alpha1, cvbval_t NHGrams, cvbval_t NPerHGram)
 Creates a ShapeFinder model representing a set of rotation states of the input model. More...
 
SF CreateSelectedSF (SF sf, cvbval_t Number)
 This function creates a ShapeFinder model as a sub set of the features of another ShapeFinder model. More...
 
SF CreateSFCircle (double R, cvbval_t Threshold, TSFGradientType AFiltertype)
 Creates a ShapeFinder model for the recognition of black on white circles with a definable radius from scratch. More...
 
SF CreateSFFromImage (IMG Image, cvbdim_t Index, cvbdim_t MX, cvbdim_t MY, cvbdim_t FWL, cvbdim_t FWT, cvbdim_t FWR, cvbdim_t FWB, cvbval_t Threshold, TSFGradientType AFiltertype)
 Attempts to create a ShapeFinder model from image data. More...
 
SF CreateSFSegment (double Alpha, cvbdim_t Length, cvbval_t Threshold, TSFGradientType AFiltertype)
 Creates a ShapeFinder model for the recognition of straight edges of definable length and orientation. More...
 
SF CreateSSymmetricSF (SF sf, double Rho0, double Rho1, cvbval_t NHGrams, cvbval_t NPerHGram)
 Creates a ShapeFinder model representing a set of scale states of the input model. More...
 
SF CreateTransformedSF (SF sf, TMatrix M)
 Creates a ShapeFinder model by geometrically transforming the input model. More...
 
SF CreateTranslatedSF (SF sf, cvbdim_t DX, cvbdim_t DY)
 This function creates a ShapeFinder model representing a translation of the input model by a given vector. More...
 
SF DeleteSFFeatures (SF sf, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom)
 Creates a ShapeFinder model with a reduced feature set. More...
 
SF MergeSF (SF sf1, SF sf2)
 Creates a ShapeFinder model by merging the features of the two input models. More...
 
cvbbool_t SFSearch (SF Sf, IMG Image, cvbdim_t Index, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, cvbdim_t Pitch, cvbdim_t &X, cvbdim_t &Y, cvbdim_t &H, cvbval_t &Z, IMG &O)
 Use a ShapeFinder model for finding occurrences of the trained pattern in an image. More...
 

Detailed Description

Function Documentation

◆ ConcatenateSF()

SF ConcatenateSF ( SF  sf1,
SF  sf2 
)

Creates a ShapeFinder model by concatenating the feature lists of the two input models.

Concatenation this case means that the planes (= class IDs) from sf2 are appended to those of sf1. Therefore, the class indices of sf1 are preserved and new classes are created in the resulting model for the class indices contributed from sf2.

Example: Assume sf1 has class indices 0, 1, and 2 and sf2 has indices 0 and 1. Then the resulting model has class indices 0, 1, 2, 3, and 4, and the features of indices 0 and 1 of sf2 are mapped to indices 3 and 4 in the resulting model.

Attention
It is not possible to merge two models with different TSFGradientType specifications (use GetSFGradienttype to query the gradient types of the input models when in doubt).
Parameters
[in]sf1Handle to the first ShapeFinder input model to be concatenated.
[in]sf2Handle to the second ShapeFinder input model to be concatenated.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
See also
Concatenations and Multi-Class Models, MergeSF

◆ CreateContrastReversedSF()

SF CreateContrastReversedSF ( SF  sf)

Creates a ShapeFinder model by reversing the contrasts of the input model.

This function effectively rotates the direction of all features' gradients by 180° in the new model, which amounts to the reversal of all feature contrasts.

With this function, creating a classifier that is invulnerable to partial contrast reversal (something that can easily happen on shiny surfaces) becomes easy:

// precondition: sf holds the ShapeFinder model to be made invariant
auto sfInverted = CreateContrastReversedSF(sf);
auto sfInvariant = MergeSF(sf, sfInverted);
ReleaseObject(sf);
ReleaseObject(sfInverted);
sf = sfInvariant;
sfInvariant = nullptr;
SF CreateContrastReversedSF(SF sf)
Creates a ShapeFinder model by reversing the contrasts of the input model.
Definition: FromDelphi_USF.cpp:1378
SF MergeSF(SF sf1, SF sf2)
Creates a ShapeFinder model by merging the features of the two input models.
Definition: FromDelphi_USF.cpp:1978
Parameters
[in]sfHandle to the input ShapeFinder model.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from the CVCImg.dll once the model is no longer needed. If the function fails a nullptr will be returned.
See also
Superposition and Merging of Models

◆ CreateDuplicateSF()

SF CreateDuplicateSF ( SF  sf)

Creates a copy of a ShapeFinder model.

Parameters
[in]sfHandle to the model to be copied.
Returns
If the function is successful a handle to the created ShapeFinder model is returned. Remember to call ReleaseObject from the CVCImg.dll once this object is no longer needed. If the function fails, a nullptr will be returned.

◆ CreateRSymmetricSF()

SF CreateRSymmetricSF ( SF  sf,
double  Alpha0,
double  Alpha1,
cvbval_t  NHGrams,
cvbval_t  NPerHGram 
)

Creates a ShapeFinder model representing a set of rotation states of the input model.

The rotation states will be calculated over the specified range of angles and resolved in the specified granularity.

Attention
Choosing NHGrams or NPerHGram too large may result in excessive memory requirements and a considerable slowdown of the search function when called with the resulting classifier.
Parameters
[in]sfHandle to the ShapeFinder model to be transformed.
[in]Alpha0Begin of range of rotation angles in degrees.
[in]Alpha1End of range of rotation angles in degrees.
[in]NHGramsNumber of accumulators to be used to cover the range of angles. This parameter will co-determine the ability of the resulting ShapeFinder model to resolve minor angle differences.
[in]NPerHGramNumber of rotation states per accumulator. This parameter will co-determine the ability of the resulting ShapeFinder model to resolve minor angle differences.
Returns
If the function is successful a handle to the created ShapeFinder model will be returned. Remember to call ReleaseObject from the CVCImg.dll once the model is no longer needed. If the function fails a nullptr will be returned.
See also
Rotation Symmetry

◆ CreateSelectedSF()

SF CreateSelectedSF ( SF  sf,
cvbval_t  Number 
)

This function creates a ShapeFinder model as a sub set of the features of another ShapeFinder model.

The number of features that ends up in the new model is selectable through the Number parameter. If Number is less than the number of features in the model pointed to by sf, then all surplus features will be removed. This removal happens independently for every accumulator plane (sometimes called the class ID; the tool will try to spread the removed features evenly over the available features and planes). Therefore, the highest achievable quality for a search result determined by the thinned-out model will necessarily be lower than that of the original model.

If Number is greater than the number of features available in the model pointed to by sf, the result of calling CreateSelectedSF will be the same as calling CreateDuplicateSF.

Parameters
[in]sfHandle to the ShapeFinder input model.
[in]NumberNumber of features to be selected.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
See also
Rating and Selecting Features

◆ CreateSFCircle()

SF CreateSFCircle ( double  R,
cvbval_t  Threshold,
TSFGradientType  AFiltertype 
)

Creates a ShapeFinder model for the recognition of black on white circles with a definable radius from scratch.

With ShapeFinder it is not only possible to generate models for object recognition from images, they may also be constructed artificially from circles and lines by merging (MergeSF) these basic elements.

Parameters
[in]RRadius of the circle model.
[in]ThresholdThreshold for the gradient slope to be used for subsequent recognition processes. May later on be modified using the SetSFThreshold function.
[in]AFiltertypeType of gradient algorithm to be used. Must be either SFF_Roberts or SFF_Sobel. See also TSFGradientType.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
See also
Circles, Gradients, MergeSF, CreateSFSegment

◆ CreateSFFromImage()

SF CreateSFFromImage ( IMG  Image,
cvbdim_t  Index,
cvbdim_t  MX,
cvbdim_t  MY,
cvbdim_t  FWL,
cvbdim_t  FWT,
cvbdim_t  FWR,
cvbdim_t  FWB,
cvbval_t  Threshold,
TSFGradientType  AFiltertype 
)

Attempts to create a ShapeFinder model from image data.

If successful, the resulting ShapeFinder model may afterwards be used with any function that is able to work on a ShapeFinder model, but not those that are requiring 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]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]AFiltertypeGradient filter to be used (see Gradients). For possible values refer to TSFGradientType.
Returns
If the function is successful a handle to the newly created ShapeFinder model will returned. If the function fails it will return a nullptr.
See also
ReleaseSF, Training and Models

◆ CreateSFSegment()

SF CreateSFSegment ( double  Alpha,
cvbdim_t  Length,
cvbval_t  Threshold,
TSFGradientType  AFiltertype 
)

Creates a ShapeFinder model for the recognition of straight edges of definable length and orientation.

With ShapeFinder it is not only possible to generate models for object recognition from images, they may also be constructed artificially from circles and lines by merging (MergeSF) these basic elements.

Parameters
[in]AlphaOrientation of the edges to be detected in degrees.
[in]LengthSpecifies the length in pixels of the edges to be detected.
[in]ThresholdThreshold for the gradient slope to be used for subsequent recognition processes. May later on be modified using the SetSFThreshold function.
[in]AFiltertypeType of gradient algorithm to be used. Must be either SFF_Roberts or SFF_Sobel. See also TSFGradientType.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
See also
Line Segments, Gradients, CreateSFCircle

◆ CreateSSymmetricSF()

SF CreateSSymmetricSF ( SF  sf,
double  Rho0,
double  Rho1,
cvbval_t  NHGrams,
cvbval_t  NPerHGram 
)

Creates a ShapeFinder model representing a set of scale states of the input model.

The scale states will be calculated over the specified range of scale factors and resolved in the specified granularity.

Attention
Choosing NHGrams or NPerHGram too large may result in excessive memory requirements and a considerable slowdown of the search function when called with the resulting classifier.
Parameters
[in]sfHandle to the ShapeFinder model to be transformed.
[in]Rho0Begin of range of scale factors.
[in]Rho1End of range of scale factors.
[in]NHGramsNumber of accumulators to be used to cover the range of scale factors. This parameter will co-determine the ability of the resulting ShapeFinder model to resolve minor scale differences.
[in]NPerHGramNumber of scale states per accumulator. This parameter will co-determine the ability of the resulting ShapeFinder model to resolve minor scale differences.
Returns
If the function is successful a handle to the created ShapeFinder model will be returned. Remember to call ReleaseObject from the CVCImg.dll once the model is no longer needed. If the function fails a nullptr will be returned.
See also
CreateRSymmetricSF

◆ CreateTransformedSF()

SF CreateTransformedSF ( SF  sf,
TMatrix  M 
)

Creates a ShapeFinder model by geometrically transforming the input model.

Parameters
[in]sfHandle to the ShapeFinder model to be transformed.
[in]M2x2 matrix specifying the transformation.
Returns
If the function is successful a handle to the newly created ShapeFinder model is returned. Remember to call ReleaseObject form the CVCImg.dll on it once it is no longer needed. If the function fails it will return a nullptr.
See also
Transforming Models with 2x2 Matrices

◆ CreateTranslatedSF()

SF CreateTranslatedSF ( SF  sf,
cvbdim_t  DX,
cvbdim_t  DY 
)

This function creates a ShapeFinder model representing a translation of the input model by a given vector.

Parameters
[in]sfHandle to the ShapeFinder model to be translated..
[in]DXX-component of the translation vector.
[in]DYY-component of the translation vector.
Returns
If the function is successful a handle to the newly created ShapeFinder model is returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
See also
Synthetic Model Creation

◆ DeleteSFFeatures()

SF DeleteSFFeatures ( SF  sf,
cvbdim_t  Left,
cvbdim_t  Top,
cvbdim_t  Right,
cvbdim_t  Bottom 
)

Creates a ShapeFinder model with a reduced feature set.

The new classifier will contain all the features of the input classifier except for those that are located in the rectangle defined by the Left, Top, Right and Bottom parameters. Left, Top, Right and Bottom are measured relative to the model origin, so providing negative values here is perfectly acceptable.

Parameters
[in]sfHandle to the ShapeFinder input model.
[in]LeftLeft edge (relative to the model origin) of the rectangle from which to remove the features.
[in]TopTop edge (relative to the model origin) of the rectangle from which to remove the features.
[in]RightRight edge (relative to the model origin) of the rectangle from which to remove the features.
[in]BottomBottom edge (relative to the model origin) of the rectangle from which to remove the features.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
Example
Remove the center part of a ShapeFinder model
// precondition: sf contains a valid model
auto sfReduced = DeleteSFFeatures(sf, -50, -50, 50, 50);
ReleaseObject(sf);
sf = sfReduced;
sfReduced = nullptr;
SF DeleteSFFeatures(SF sf, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom)
Creates a ShapeFinder model with a reduced feature set.
Definition: FromDelphi_USF.cpp:1538

◆ MergeSF()

SF MergeSF ( SF  sf1,
SF  sf2 
)

Creates a ShapeFinder model by merging the features of the two input models.

Unlike ConcatenateSF, MergeSF will append the available feature lists for equal class indices (= model planes): The features of class index 0 in model sf1 will be merged with those of class index 0 in sf2 to the class index 0 of the resulting model and so on for all the other available indices (whereas ConcatenateSF would simply append the indices of sf2 after the last index of sf1).

Attention
It is not possible to merge two models with different TSFGradientType specifications (use GetSFGradienttype to query the gradient types of the input models when in doubt).
Parameters
[in]sf1Handle to the first ShapeFinder input model to be merged.
[in]sf2Handle to the second ShapeFinder input model to be merged.
Returns
If the function is successful a handle to the newly created ShapeFinder model will be returned. Remember to call ReleaseObject from CVCImg.dll once this object is no longer needed. If the function fails a nullptr will be returned.
See also
Superposition and Merging of Models, ConcatenateSF

◆ SFSearch()

cvbbool_t SFSearch ( SF  Sf,
IMG  Image,
cvbdim_t  Index,
cvbdim_t  Left,
cvbdim_t  Top,
cvbdim_t  Right,
cvbdim_t  Bottom,
cvbdim_t  Pitch,
cvbdim_t &  X,
cvbdim_t &  Y,
cvbdim_t &  H,
cvbval_t &  Z,
IMG &  O 
)

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

The search is carried out by calculating the amount of matching features for the available model planes of the classifier inside the search window (see The ShapeFinder Algorithm).

The value, position and class index corresponding to the global accumulator maximum are returned (in the output parameters Z, X, Y, and H) as well as the search accumulator itself, which may be used for a more detailed analysis.

Attention
Even if the accumulator is not being used for further analysis it is absolutely necessary to call ReleaseObject from the CVCImg.dll on it, otherwise the accumulator will continue to occupy memory.
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 ShapeFinder model used for searching.
[in]ImageHandle to the image in which to look for the patterns trained into the ShapeFinder model sf.
[in]IndexImage plane 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]PitchInverse resolution of the accumulator (see ShapeFinder and Pattern Recognition). Must be in the range [1...4]. Values outside this range will be clamped to this range. Normally a value of 1 should be used here. Higher values give slightly higher recognition speed, but decrease the accuracy of the result position.
[out]XX-position of the accumulator maximum.
[out]YY-position of the accumulator maximum.
[out]HClass index (plane of the accumulator) in which the maximum is located. Interpretation depends on the way the ShapeFinder model has been composed. For example, if the ShapeFinder model was generated with CreateRSymmetricSF, the class index will correspond to a rotation state that can be deduced from the parameters that were passed to CreateRSymmetricSF.
[out]ZValue of the accumulator maximum (may be interpreted as a quality measure for the result).
[out]OHandle to the accumulator. The accumulator is a regular Common Vision Blox image with as many planes as the ShapeFinder model has different class indices. Each plane in the accumulator has pixels with 16 bits. The pixel coordinates in the accumulator correspond to those in the input Image, but only the values inside the search rectangle are usable - read and write access outside the search rectangle will yield undefined results! Do not forget to release the accumulator resources by calling ReleaseObject on it once it is no longer needed!
Returns
A nonzero (TRUE) return value indicates success (in which case the output parameters may be evaluated) while zero (FALSE) indicates an unrecoverable error. In this case the output parameters are to be ignored.
Note that a TRUE return values does not mean that a proper result has been found! This should be determined by looking at the value returned in Z.