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] sf Handle 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] sf Handle 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] sf Handle 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] sf Handle 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] sf Handle 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]	sf	Handle to the ShapeFinder/ShapeFinder2 model for which to query the feature window.
[out]	FWL	Left edge of the feature window relative to the model origin (typically a negative value).
[out]	FWT	Top edge of the feature window relative to the model origin (typically a negative value).
[out]	FWR	Right edge of the feature window relative to the model origin.
[out]	FWB	Bottom 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] sf Handle 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
0°	pink
90°	cyan
180°	green
270°	red

Parameters

[in]	ClassID	Class id of the features in `sf` for which to create the color representation image. `-1` superimposes all available classes.
[in]	sf	Handle 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] sf Handle 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] handle Handle 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] handle Handle 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]	sf	If loading the model succeeded, this parameter will receive the handle to the ShapeFinder/ShapeFinder2 model.
[in]	szFileName	Name 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]	sf	If loading the model succeeded, this parameter will receive the handle to the ShapeFinder/ShapeFinder2 model.
[in]	szFileName	Name 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]	Image	Handle to input image.
[out]	ImgOut	Receives 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] sf Handle 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]	sf	Handle to the ShapeFinder model for which the angular tolerance is to be set.
[in]	AngularTolerance	Angular 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]	sf	Handle to the ShapeFinder/ShapeFinder2 model for which to set the comment.
[in]	szComment	Comment 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]	sf	Handle to the ShapeFinder/ShapeFinder2 model for which to set the comment.
[in]	szComment	Comment 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]	sf	Handle to the ShapeFinder model for which the threshold is to be set.
[in]	Threshold	Minimum 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]	ImageIn	Handle to the image for which to calculate the histogram.
[in]	Index	Image plane for which to calculate the histogram.
[in]	Left	Left edge of the area of interest for which to calculate the histogram.
[in]	Top	Top edge of the area of interest for which to calculate the histogram.
[in]	Right	Right edge of the area of interest for which to calculate the histogram.
[in]	Bottom	Bottom edge of the area of interest for which to calculate the histogram.
[in]	FilterType	Gradient 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]	Histogram	An 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] sf Handle 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]	sf	Handle to the ShapeFinder or ShapeFinder2 model to be stored.
[in]	FileName	Name 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]	sf	Handle to the ShapeFinder or ShapeFinder2 model to be stored.
[in]	FileName	Name 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

Functions

Detailed Description

Function Documentation

◆ GetSFAngularTolerance()

◆ GetSFClassNumber()

◆ GetSFComment()

◆ GetSFCommentW()

◆ GetSFFeatureNumber()

◆ GetSFFeatureWindow()

◆ GetSFGradienttype()

◆ GetSFImage()

◆ GetSFThreshold()

◆ IsSF()

◆ IsSF2()

◆ LoadSF()

◆ LoadSFW()

◆ PyramidFilter()

◆ ReleaseSF()

◆ SetSFAngularTolerance()

◆ SetSFComment()

◆ SetSFCommentW()

◆ SetSFThreshold()

◆ SFGradHistogram()

◆ ShareSF()

◆ StoreSF()

◆ StoreSFW()