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]	sf1	Handle to the first ShapeFinder input model to be concatenated.
[in]	sf2	Handle 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;

Parameters

[in] sf Handle 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] sf Handle 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]	sf	Handle to the ShapeFinder model to be transformed.
[in]	Alpha0	Begin of range of rotation angles in degrees.
[in]	Alpha1	End of range of rotation angles in degrees.
[in]	NHGrams	Number 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]	NPerHGram	Number 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]	sf	Handle to the ShapeFinder input model.
[in]	Number	Number 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]	R	Radius of the circle model.
[in]	Threshold	Threshold for the gradient slope to be used for subsequent recognition processes. May later on be modified using the SetSFThreshold function.
[in]	AFiltertype	Type 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]	Image	Handle to the image containing the data from which to train the model.
[in]	Index	Color plane from which to train the model.
[in]	MX	X-position in the `Image` from which to train the model.
[in]	MY	Y-position in the `Image` from which to train the model.
[in]	FWL	Left extent of the feature window for training (relative to `MX` - typically a negative value).
[in]	FWT	Top extent of the feature window for training (relative to `MY` - typically a negative value).
[in]	FWR	Right extent of the feature window for training (relative to `MX`).
[in]	FWB	Bottom extent of the feature window for training (relative to `MY`).
[in]	Threshold	Threshold 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]	AFiltertype	Gradient 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]	Alpha	Orientation of the edges to be detected in degrees.
[in]	Length	Specifies the length in pixels of the edges to be detected.
[in]	Threshold	Threshold for the gradient slope to be used for subsequent recognition processes. May later on be modified using the SetSFThreshold function.
[in]	AFiltertype	Type 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]	sf	Handle to the ShapeFinder model to be transformed.
[in]	Rho0	Begin of range of scale factors.
[in]	Rho1	End of range of scale factors.
[in]	NHGrams	Number 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]	NPerHGram	Number 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]	sf	Handle to the ShapeFinder model to be transformed.
[in]	M	2x2 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]	sf	Handle to the ShapeFinder model to be translated..
[in]	DX	X-component of the translation vector.
[in]	DY	Y-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]	sf	Handle to the ShapeFinder input model.
[in]	Left	Left edge (relative to the model origin) of the rectangle from which to remove the features.
[in]	Top	Top edge (relative to the model origin) of the rectangle from which to remove the features.
[in]	Right	Right edge (relative to the model origin) of the rectangle from which to remove the features.
[in]	Bottom	Bottom 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;

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.
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]	sf1	Handle to the first ShapeFinder input model to be merged.
[in]	sf2	Handle 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]	Sf	Handle to the ShapeFinder model used for searching.
[in]	Image	Handle to the image in which to look for the patterns trained into the ShapeFinder model `sf`.
[in]	Index	Image plane to be searched.
[in]	Left	Left coordinate of the search area in the image (in pixel coordinates).
[in]	Top	Top coordinate of the search area in the image (in pixel coordinates).
[in]	Right	Right coordinate of the search area in the image (in pixel coordinates).
[in]	Bottom	Bottom coordinate of the search area in the image (in pixel coordinates).
[in]	Pitch	Inverse 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]	X	X-position of the accumulator maximum.
[out]	Y	Y-position of the accumulator maximum.
[out]	H	Class 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]	Z	Value of the accumulator maximum (may be interpreted as a quality measure for the result).
[out]	O	Handle 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.


Contact Legal Privacy Statement	Copyright © 2023.
	All rights reserved.

Functions

Detailed Description

Function Documentation

◆ ConcatenateSF()

◆ CreateContrastReversedSF()

◆ CreateDuplicateSF()

◆ CreateRSymmetricSF()

◆ CreateSelectedSF()

◆ CreateSFCircle()

◆ CreateSFFromImage()

◆ CreateSFSegment()

◆ CreateSSymmetricSF()

◆ CreateTransformedSF()

◆ CreateTranslatedSF()

◆ DeleteSFFeatures()

◆ MergeSF()

◆ SFSearch()