ShapeFinder (SF.dll) 15.0
Functions for ShapeFinder and ShapeFinder2

Functions

cvbval_t GetSFAngularTolerance (SF sf)
 Retrieves the currently set angular tolerance parameter from the specified ShapeFinder/ShapeFinder2 model. More...
 
cvbval_t GetSFClassNumber (SF sf)
 Returns the total number of classes in a ShapeFinder or ShapeFinder2 model. More...
 
const char * GetSFComment (SF sf)
 Returns a pointer the comment that has been set on a ShapeFinder/ShapeFinder2 model. More...
 
const wchar_t * GetSFCommentW (SF sf)
 Returns a pointer the comment that has been set on a ShapeFinder/ShapeFinder2 model. More...
 
cvbval_t GetSFFeatureNumber (SF sf)
 Returns the total number of features in a given ShapeFinder or ShapeFinder2 model. More...
 
cvbbool_t GetSFFeatureWindow (SF sf, cvbdim_t &FWL, cvbdim_t &FWT, cvbdim_t &FWR, cvbdim_t &FWB)
 This function returns feature window of a ShapeFinder/ShapeFinder2 model. More...
 
TSFGradientType GetSFGradienttype (SF sf)
 Returns the type of gradient calculation that has been used for creating a ShapeFinder/ShapeFinder2 model. More...
 
IMG GetSFImage (cvbval_t ClassID, SF sf)
 Creates a color coded image representation of the given ShapeFinder model. More...
 
cvbval_t GetSFThreshold (SF sf)
 Retrieves the currently set threshold for the gradient slope from a ShapeFinder or ShapeFinder2 model. More...
 
cvbbool_t IsSF (SF handle)
 Verifies whether a handle refers to a valid ShapeFinder or ShapeFinder2 model. More...
 
cvbbool_t IsSF2 (SF handle)
 Verifies whether a handle refers to a valid ShapeFinder2 model. More...
 
cvbbool_t LoadSF (SF &sf, const char *szFileName)
 Loads a ShapeFinder or ShapeFinder2 model from a file. More...
 
cvbbool_t LoadSFW (SF &sf, const wchar_t *szFileName)
 Loads a ShapeFinder or ShapeFinder2 model from a file. More...
 
cvbbool_t PyramidFilter (IMG Image, IMG &ImgOut)
 Creates a zoomed version of the input image. More...
 
cvbval_t ReleaseSF (SF &sf)
 Decreases the internal reference count of a ShapeFinder or a ShapeFinder2 model. More...
 
cvbbool_t SetSFAngularTolerance (SF sf, cvbval_t AngularTolerance)
 Modifies the angular tolerance parameter of a ShapeFinder or ShapeFinder2 model. More...
 
void SetSFComment (SF sf, const char *szComment)
 Sets a comment string on a ShapeFinder/ShapeFinder2 model. More...
 
void SetSFCommentW (SF sf, const wchar_t *szComment)
 Sets a comment string on a ShapeFinder/ShapeFinder2 model. More...
 
cvbbool_t SetSFThreshold (SF sf, cvbval_t Threshold)
 Modifies the threshold for the gradient slope associated on a ShapeFinder or ShapeFinder2 model. More...
 
cvbbool_t SFGradHistogram (IMG ImageIn, cvbdim_t Index, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, TSFGradientType FilterType, THistogram Histogram)
 Computes a histogram of gradient slopes for given image data. More...
 
cvbval_t ShareSF (SF sf)
 Increases the internal reference count of a ShapeFinder or ShapeFinder2 model. More...
 
cvbbool_t StoreSF (SF sf, const char *FileName)
 Stores a ShapeFinder or ShapeFinder2 model in a file. More...
 
cvbbool_t StoreSFW (SF sf, const wchar_t *FileName)
 Stores a ShapeFinder or ShapeFinder2 model in a file. More...
 

Detailed Description

Function Documentation

◆ GetSFAngularTolerance()

cvbval_t GetSFAngularTolerance ( SF  sf)

Retrieves the currently set angular tolerance parameter from the specified ShapeFinder/ShapeFinder2 model.

The angular tolerance defines a maximum delta at which the angle of two features (one from a ShapeFinder/ShapeFinder2 model, one found in an image) are still consider to coincide. Internally, angles are coded as values from the range [0...255] and by default the angular tolerance is set to 0 so angles that differ by up to ±0.7° are considered to be identical. Higher values for the angular tolerance may be defined via SetSFAngularTolerance and increase the span by ±0.7° per integer value added.

Parameters
[in]sfHandle to the ShapeFinder model for which the angular tolerance is to be retrieved.
Returns
Currently set angular tolerance level or -1 if sf does not refer to a valid ShapeFinder/ShapeFinder2 model.
See also
Directional Quantization, Angular Tolerance, and Overview of Recognition Parameters, SetSFAngularTolerance

◆ GetSFClassNumber()

cvbval_t GetSFClassNumber ( SF  sf)

Returns the total number of classes in a ShapeFinder or ShapeFinder2 model.

A ShapeFinder model may more often than not have more than just one class trained. What exactly a class corresponds to depends on how the ShapeFinder model has been constructed. For example it is possible (and a perfectly valid use case) to train different objects into the different classes of a ShapeFinder model. When working with CreateRSymmetricSF or CreateSSymmetricSF the different "classes" will in fact refer to different rotation or scale states instead.

For a ShapeFinder2 model it is generally possible to query the class number, however the use of the different classes in that case is opaque and it is not possible (nor is it necessary with a ShapeFinder2 model) to make sense of the different classes.

When using a ShapeFinder model with SFSearch, the resulting search accumulator will have a number of planes identical to the number of classes the ShapeFinder model has.

Parameters
[in]sfHandle to the ShapeFinder model to be queried.
Returns
Number of classes in the ShapeFinder model referred to by sf. If sf does not refer to a valid ShapeFinder/ShapeFinder2 model -1 will be returned instead.

◆ GetSFComment()

const char * GetSFComment ( SF  sf)

Returns a pointer the comment that has been set on a ShapeFinder/ShapeFinder2 model.

Note: If the comment contains characters that are not mappable to the process's current code page then those characters will be replaced with '?' characters.

Attention
This function returns a pointer to the model's internal ASCII representation of the model comment. This pointer is only valid as long as the model itself exists. Dereferencing the returned pointer after the model has been destroyed will produce undefined behavior (possibly access violations).
Parameters
[in]sfHandle to the ShapeFinder model from which to retrieve the comment string.
Returns
Pointer to the ASCII representation of the comment stored in the model. Do not free this pointer. Do not dereference this pointer after the model passed in sf has expired.

◆ GetSFCommentW()

const wchar_t * GetSFCommentW ( SF  sf)

Returns a pointer the comment that has been set on a ShapeFinder/ShapeFinder2 model.

Attention
This function returns a pointer to the model's internal Unicode representation of the model comment. This pointer is only valid as long as the model itself exists. Dereferencing the returned pointer after the model has been destroyed will produce undefined behavior (possibly access violations).
Parameters
[in]sfHandle to the ShapeFinder model from which to retrieve the comment string.
Returns
Pointer to the Unicode representation of the comment stored in the model. Do not free this pointer. Do not dereference this pointer after the model passed in sf has expired.

◆ GetSFFeatureNumber()

cvbval_t GetSFFeatureNumber ( SF  sf)

Returns the total number of features in a given ShapeFinder or ShapeFinder2 model.

Parameters
[in]sfHandle to the ShapeFinder model to be queried.
Returns
Number of features in the model referred to by sf. If sf does not refer to a valid ShapeFinder/ShapeFinder2 model, -1 will be returned.

◆ GetSFFeatureWindow()

cvbbool_t GetSFFeatureWindow ( SF  sf,
cvbdim_t &  FWL,
cvbdim_t &  FWT,
cvbdim_t &  FWR,
cvbdim_t &  FWB 
)

This function returns feature window of a ShapeFinder/ShapeFinder2 model.

The feature window is the smalled axis-parallel rectangle containing the displacement vector (location) of all features of a model. It is measured relative to the model's origin/center, therefore the left and top edge will usually have negative values.

Note that the feature window returned by GetSFFeatureWindow may in fact be smaller than the feature window that was originally specified when CreateSFFromImage, CreateSF2, CreateSF2Ex or CreateSF2ExEx was called. For ShapeFinder2 models the feature window originally passed to the training function may be queried using GetSF2TrainingWindow.

Parameters
[in]sfHandle to the ShapeFinder/ShapeFinder2 model for which to query the feature window.
[out]FWLLeft edge of the feature window relative to the model origin (typically a negative value).
[out]FWTTop edge of the feature window relative to the model origin (typically a negative value).
[out]FWRRight edge of the feature window relative to the model origin.
[out]FWBBottom edge of the feature window relative to the model origin.
Returns
TRUE if the feature window was queries successfully, FALSE if sf does not refer to a valid model (in this case the parameters FLW, FWT, FWR and FWB will not be modified).
See also
Training and Models

◆ GetSFGradienttype()

TSFGradientType GetSFGradienttype ( SF  sf)

Returns the type of gradient calculation that has been used for creating a ShapeFinder/ShapeFinder2 model.

See TSFGradientType for the available methods. Note that a ShapeFinder2 model will always use SFF_Sobel.

Parameters
[in]sfHandle to the ShapeFinder model for which to query the gradient type.
Returns
Gradient type (either SFF_Roberts or SFF_Sobel). If sf does not refer to a valid model, SFF_Undefined will be returned.
See also
Gradients, TSFGradientType

◆ GetSFImage()

IMG GetSFImage ( cvbval_t  ClassID,
SF  sf 
)

Creates a color coded image representation of the given ShapeFinder model.

The resulting image is black where there are no features in the model, and the available features will be represented by colored pixels for which the color represents the orientation of the feature's gradient:

Angle Color
pink
90° cyan
180° green
270° red
Parameters
[in]ClassIDClass id of the features in sf for which to create the color representation image. -1 superimposes all available classes.
[in]sfHandle to the ShapeFinder model from which to create the color representation.
Returns
If the function is successful a handle to a Common Vision Blox image containing the model's color representation will be returned. Dispose of this image by calling ReleaseObject from the CVCImg.dll once it is no longer needed.

◆ GetSFThreshold()

cvbval_t GetSFThreshold ( SF  sf)

Retrieves the currently set threshold for the gradient slope from a ShapeFinder or ShapeFinder2 model.

See also: Training and Models and Overview of Recognition Parameters. The slope threshold is initially set when the model is created and will be applied whenever the model is used in a search operation. It may be modified using the function SetSFThreshold.

Parameters
[in]sfHandle to the ShapeFinder model from which the threshold is to be determined.
Returns
Threshold retrieved from specified model. -1 if the specified model is invalid.
See also
Training and Models, Overview of Recognition Parameters, SetSFThreshold.

◆ IsSF()

cvbbool_t IsSF ( SF  handle)

Verifies whether a handle refers to a valid ShapeFinder or ShapeFinder2 model.

Use this function with a given handle to determine whether or not it refers to a valid ShapeFinder or ShapeFinder2 model. To find out whether it refers to a ShapeFinder or a ShapeFinder2 model use IsSF2.

Parameters
[in]handleHandle to be checked.
Returns
TRUE (non-zero value) if handle refers to a valid ShapeFinder or ShapeFinder2 model, FALSE (0) otherwise.
See also
IsSF2, Object Management and File IO

◆ IsSF2()

cvbbool_t IsSF2 ( SF  handle)

Verifies whether a handle refers to a valid ShapeFinder2 model.

Use this function with a given handle to determine whether it refers to a valid ShapeFinder2 model.

Since
Common Vision Blox 13.00.001
Parameters
[in]handleHandle to be checked.
Returns
TRUE (non-zero value) if handle refers to a valid ShapeFinder2 model, FALSE (0) otherwise.
See also
IsSF, Object Management and File IO

◆ LoadSF()

cvbbool_t LoadSF ( SF sf,
const char *  szFileName 
)

Loads a ShapeFinder or ShapeFinder2 model from a file.

If the function succeeds, the handle returned in the sf parameter will point to the loaded ShapeFinder/ShapeFinder2 model. All ShapeFinder and ShapeFinder2 models are reference counted objects that can be used with the functions ShareObject and ReleaseObject from the CVCImg.dll.

Remember to free the resources allocated by a model by calling ReleaseObject on it once it is no longer needed.

Parameters
[out]sfIf loading the model succeeded, this parameter will receive the handle to the ShapeFinder/ShapeFinder2 model.
[in]szFileNameName of the file from which to load the model.
Returns
TRUE (non-zero value) on success, FALSE (0) otherwise.
See also
StoreSF, StoreSFW, Object Management and File IO

◆ LoadSFW()

cvbbool_t LoadSFW ( SF sf,
const wchar_t *  szFileName 
)

Loads a ShapeFinder or ShapeFinder2 model from a file.

If the function succeeds, the handle returned in the sf parameter will point to the loaded ShapeFinder/ShapeFinder2 model. All ShapeFinder and ShapeFinder2 models are reference counted objects that can be used with the functions ShareObject and ReleaseObject from the CVCImg.dll.

Remember to free the resources allocated by a model by calling ReleaseObject on it once it is no longer needed.

Since
Common Vision Blox 13.00.000
Parameters
[out]sfIf loading the model succeeded, this parameter will receive the handle to the ShapeFinder/ShapeFinder2 model.
[in]szFileNameName of the file from which to load the model.
Returns
TRUE (non-zero value) on success, FALSE (0) otherwise.
See also
StoreSF, StoreSFW, Object Management and File IO

◆ PyramidFilter()

cvbbool_t PyramidFilter ( IMG  Image,
IMG &  ImgOut 
)

Creates a zoomed version of the input image.

This function is internally used during the generation of a ShapeFinder2 model for building the coarse feature scales. It creates a version of the input image that has been reduced in width and height by a factor 2 (and has been low-pass filtered prior to downscaling).

Parameters
[in]ImageHandle to input image.
[out]ImgOutReceives the handle to the downscaled image. Remember to call ReleaseObject from the CVCImg.dll once this image is no longer needed.
Returns
TRUE if the filter operation succeeded, FALSE otherwise (typical error reasons are invalid input image handles or out-of-memory situations).

◆ ReleaseSF()

cvbval_t ReleaseSF ( SF sf)

Decreases the internal reference count of a ShapeFinder or a ShapeFinder2 model.

Decrementing the reference count of a model once it is no longer needed is essential to prevent memory leaks. Always call ReleaseObject on objects that your code has created once they are no longer needed.

Parameters
[in,out]sfHandle to the ShapeFinder or ShapeFinder2 model to be released. If the referenced model ceases to exist after the ReleaseSF call a nullptr will be set on this parameter, otherwise it will not be touched.
Returns
Reference count of the model after the call. If the model has been removed from memory, this function will return 0. If an invalid handle was passed, the return value will be -1.
See also
ShareSF, Object Management and File IO

◆ SetSFAngularTolerance()

cvbbool_t SetSFAngularTolerance ( SF  sf,
cvbval_t  AngularTolerance 
)

Modifies the angular tolerance parameter of a ShapeFinder or ShapeFinder2 model.

The angular tolerance defines a maximum delta at which the angle of two features (one from a ShapeFinder/ShapeFinder2 model, one found in an image) are still consider to coincide. Internally, angles are coded as values from the range [0...255] and by default the angular tolerance is set to 0 so angles that differ by up to ±0.7° are considered to be identical. Higher values for the angular tolerance increase the span by ±0.7° per integer value added.

Note that setting the angular tolerance to higher values may at some point also notable increase the risk of getting more false positive results from ShapeFinder.

Parameters
[in]sfHandle to the ShapeFinder model for which the angular tolerance is to be set.
[in]AngularToleranceAngular tolerance to be set.
Returns
TRUE if the angular tolerance was updated, FALSE otherwise (sf did not refer to a valid ShapeFinder/ShapeFinder2 model).
See also
Directional Quantization, Angular Tolerance, and Overview of Recognition Parameters, GetSFAngularTolerance

◆ SetSFComment()

void SetSFComment ( SF  sf,
const char *  szComment 
)

Sets a comment string on a ShapeFinder/ShapeFinder2 model.

The comment can be any text and it will be stored with the model file. Use GetSFComment to retrieve the comment.

Parameters
[in]sfHandle to the ShapeFinder/ShapeFinder2 model for which to set the comment.
[in]szCommentComment to be stored with the model.

◆ SetSFCommentW()

void SetSFCommentW ( SF  sf,
const wchar_t *  szComment 
)

Sets a comment string on a ShapeFinder/ShapeFinder2 model.

The comment can be any text and it will be stored with the model file. Use GetSFComment to retrieve the comment.

Since
Common Vision Blox 13.00.000
Parameters
[in]sfHandle to the ShapeFinder/ShapeFinder2 model for which to set the comment.
[in]szCommentComment to be stored with the model.

◆ SetSFThreshold()

cvbbool_t SetSFThreshold ( SF  sf,
cvbval_t  Threshold 
)

Modifies the threshold for the gradient slope associated on a ShapeFinder or ShapeFinder2 model.

See also: Training and Models and Overview of Recognition Parameters.

Parameters
[in]sfHandle to the ShapeFinder model for which the threshold is to be set.
[in]ThresholdMinimum value for the gradient slope for a feature to be recognized during a search operation.
Returns
TRUE is the threshold has been set, FALSE if the sf does not refer to a valid ShapeFinder/ShapeFinder2 model.
See also
Training and Models and Overview of Recognition Parameters

◆ SFGradHistogram()

cvbbool_t SFGradHistogram ( IMG  ImageIn,
cvbdim_t  Index,
cvbdim_t  Left,
cvbdim_t  Top,
cvbdim_t  Right,
cvbdim_t  Bottom,
TSFGradientType  FilterType,
THistogram  Histogram 
)

Computes a histogram of gradient slopes for given image data.

Knowing the distribution of gradient slopes (i.e. gradient intensity distribution) for a given image can be useful for determining a suitable gradient threshold to use with a ShapeFinder or ShapeFinder2 model. This is particularly true for unstable illumination conditions.

Parameters
[in]ImageInHandle to the image for which to calculate the histogram.
[in]IndexImage plane for which to calculate the histogram.
[in]LeftLeft edge of the area of interest for which to calculate the histogram.
[in]TopTop edge of the area of interest for which to calculate the histogram.
[in]RightRight edge of the area of interest for which to calculate the histogram.
[in]BottomBottom edge of the area of interest for which to calculate the histogram.
[in]FilterTypeGradient calculation method to be used. This may be either SFF_Roberts or SFF_Sobel (see Gradients). Note that ShapeFinder2 models always use SFF_Sobel internally.
[in]HistogramAn array of 256 integers to receive the resulting histogram.
Returns
TRUE on success, FALSE otherwise.
See also
Gradients

◆ ShareSF()

cvbval_t ShareSF ( SF  sf)

Increases the internal reference count of a ShapeFinder or ShapeFinder2 model.

The reference count of an object should be incremented whenever ownership of the object is shared between two code entities (e.g. two threads or two forms) to make sure that the object lives long enough for all the entities sharing ownership to safely work on it.

Parameters
[in,out]sfHandle to the ShapeFinder model to be shared.
Returns
Resulting reference count after sharing. If an invalid handle was passed, the return value will be -1.
See also
ReleaseSF, Object Management and File IO

◆ StoreSF()

cvbbool_t StoreSF ( SF  sf,
const char *  FileName 
)

Stores a ShapeFinder or ShapeFinder2 model in a file.

Parameters
[in]sfHandle to the ShapeFinder or ShapeFinder2 model to be stored.
[in]FileNameName of file to which to save the ShapeFinder or ShapeFinder2 model.
Returns
TRUE (non-zero value) on success, FALSE (0) otherwise.
See also
LoadSF, LoadSFW, Object Management and File IO

◆ StoreSFW()

cvbbool_t StoreSFW ( SF  sf,
const wchar_t *  FileName 
)

Stores a ShapeFinder or ShapeFinder2 model in a file.

Since
Common Vision Blox 13.00.000
Parameters
[in]sfHandle to the ShapeFinder or ShapeFinder2 model to be stored.
[in]FileNameName of file to which to save the ShapeFinder or ShapeFinder2 model.
Returns
TRUE (non-zero value) on success, FALSE (0) otherwise.
See also
LoadSF, LoadSFW, Object Management and File IO