Data Structures
struct	VCSFInit
	Smart Finder Initialisation. More...

struct	VCSFCfg
	Smart Finder Configuration. More...

struct	VCSFPat
	Smart Finder Pattern. More...

struct	VCSFResult
	Smart Finder Result. More...

Macros
#define	VCSFInit_Default { 0, 255, 1.0, 1.0, 2,{2,0,0,0},{6,2,0,0},{3,0,0,0},{0.1,0.008,0.0,0.0},{3,1,0,0}, 2,{1,1,0,0}}

#define	vc_sf_pre_mask_small_regions(imgIn, imgOut, minPixel) vc_image_fill_small_regions(imgIn, imgOut, 0, 1, 256, 1, minPixel, 0)
	Remove Small Noise Regions from Edge Image (Macro). More...

Functions
I32	vc_sf_init (VCSFCfg cfg, VCSFInit init)
	Initializes the Smartfinder Configuration. More...

I32	vc_sf_deinit (VCSFCfg *cfg)
	Deinitializes the Smartfinder. More...

I32	vc_sf_match_image (image img, VCSFPat pat, VCSFCfg cfg, VCSFResult result)
	Finds a Pattern Location at an Image. More...

I32	vc_sf_pattern_from_img (image vec, VCSFPat pat, VCSFCfg *cfg)
	Generates a Pattern from a Vector Image. More...

I32	vc_sf_pattern_from_file (char path, VCSFPat pat, VCSFCfg *cfg)
	Reads a Pattern from a File. More...

I32	vc_sf_pattern_from_xylist_I16 (U32 pxCount, I16 xy, U8 dir, VCSFPat pat, VCSFCfg cfg)
	Generates a Pattern from a Pixel List (I16). More...

I32	vc_sf_pattern_to_file (char path, VCSFPat pat)
	Stores a Pattern in a File. More...

I32	vc_sf_pattern_free (VCSFPat *pat)
	Frees Memory of a Smartfinder Pattern Structure. More...

I32	vc_sf_searchimagepattern_generate (VCSFPat patImg, image vec, VCSFCfg *cfg)
	Convert edge search image (vector image) for matching. More...

I32	vc_sf_match_patterns (VCSFPat patImg, VCSFPat pat, VCSFCfg cfg, VCSFResult result)
	Finds a Pattern Location at a Search Image Pattern. More...

Detailed Description

The smart finder locates patterns under varying rotation or scale at an image. Depending on the needs, the detected rotation angles and scales can be specified by setting interval boundaries. Limiting angles and scales not only dramatically reduces calculation time but also enhances detection reliability.

The angle resolution is 1.4 degrees. The rotation of the pattern when trained defines the zero degree angle. Also the scale factor of 1.0 is defined as the scale of the pattern when trained.

The lesser edges are included for the pattern, the faster the algorithm works.

Minimalistic Example, please also refer to the 'vcdemo_smartfinder'!

I32  smartfinder_minimal(image *img, I8 teachIff1)
{
    I32          rc, *prc, ee;
    image        imgVec   = NULL_IMAGE;
    VCSFCfg      sfCfg    = NULL_VCSFCfg;
    VCSFPat      sfPat    = NULL_VCSFPat;
    VCSFResult   sfResult = NULL_VCSFResult;
    VCSFInit     sfInit   = VCSFInit_Default;
    // Pre-process image
    prc =  ImageAllocate(&imgVec, IMAGE_VECTOR, img->dx, img->dy);
    if(NULL==prc){ee=-1;goto fail;}
    rc =  edge_fast(img, &imgVec, 128);
    if(rc<0){ee=-2+10*rc;goto fail;}
    rc =  mask_frame(&imgVec,  0, 7, 0, 0, 0);
    if(rc<0){ee=-3+10*rc;goto fail;}
    // [ONCE] Pre-configure and initialize smart finder.
    // Important defaulting happened at:
    //   VCSFInit     sfInit = VCSFInit_Default;
    sfInit.scaleMin = 0.8;
    sfInit.scaleMax = 1.2;
    rc =  vc_sf_init(&sfCfg, &sfInit);
    if(ERR_NONE!=rc){ee=-4+10*rc; goto fail;}
    if(1==teachIff1)
    {
        // [...]
        // 
        // To generate pattern: Each vector image pixel with a magnitude of 0 is a pattern pixel.
        // So, eventually pre-process image here to only have a magnitude of 0 on as little
        // as possible, but as much as necessary pattern contour pixels.
        rc =  vc_sf_pattern_from_img(&imgVec, &sfPat, &sfCfg);
        if(rc<0){ee=-5+10*rc;goto fail;}
        rc =  vc_sf_pattern_to_file("/tmp/pattern.dat", &sfPat);
        if(rc<0){ee=-6+10*rc;goto fail;}
    }
    else
    {
        // [ONCE] Read Pattern
        rc =  vc_sf_pattern_from_file("/tmp/pattern.dat", &sfPat, &sfCfg);
        if(rc<0){ee=-7+10*rc;goto fail;}
        // [OPTIONAL] Remove Small Noise
        rc =  vc_sf_pre_mask_small_regions(&imgVec, &imgVec, 20);
        if(rc<0){ee=-8+100*rc;goto fail;}
        // [ALWAYS] Find Match
        rc =  vc_sf_match_image(&imgVec, &sfPat, &sfCfg, &sfResult);
        if(rc<0){ee=-9+10*rc;goto fail;}
        vc_sf_result_print(&sfResult);
    }
    ee=0;
fail:
    // [ONCE] Free Pattern Data
    vc_sf_pattern_free(&sfPat);
    // [ONCE] Deinitialize smart finder
    vc_sf_deinit(&sfCfg);
    ImageFree(&imgVec);
    return(ee);
}

Data Structure Documentation

◆ VCSFInit

struct VCSFInit

This structure sets up the the smart finder configuration.

Data Fields
I32	angleAng8Start	start angle of pattern in search image [-128..127] * 1.4deg, 0 is pattern angle
I32	angleAng8End	stop angle of pattern in search image [-128..127] * 1.4deg, 0 is pattern angle
F32	scaleMin	Minimum scale of pattern in search image, 1.0 is 100%
F32	scaleMax	Maximum scale of pattern in search image, 1.0 is 100%
I32	rasters
I32	patRasterSize[VCSFMaxRasters]
I32	imgRasterSize[VCSFMaxRasters]
I32	rasterSizePow[VCSFMaxRasters]
F32	patRasterScaleStep[VCSFMaxRasters]
I32	patRasterDirStep[VCSFMaxRasters]
U8	patSegments
U8	patSegWeight[VCSFMaxSegments]

◆ VCSFCfg

struct VCSFCfg

This structure contains settings for the smart finder.

◆ VCSFPat

struct VCSFPat

This structure contains a pattern for a smart finder matching operation.

◆ VCSFResult

struct VCSFResult

This structure contains the result of a smart finder match.

Data Fields
F32	x	x-coordinate of match
F32	y	y-coordinate of match
F32	dir	direction of match
F32	scale	scale of match
I32	strength	relative matching strength

Macro Definition Documentation

◆ VCSFInit_Default

#define VCSFInit_Default { 0, 255, 1.0, 1.0, 2,{2,0,0,0},{6,2,0,0},{3,0,0,0},{0.1,0.008,0.0,0.0},{3,1,0,0}, 2,{1,1,0,0}}

Smart Finder Default Settings

◆ vc_sf_pre_mask_small_regions

#define vc_sf_pre_mask_small_regions	(	imgIn,
		imgOut,
		minPixel
	)	vc_image_fill_small_regions(imgIn, imgOut, 0, 1, 256, 1, minPixel, 0)

The function removes small noise present in an edge image later used for pattern generation or pattern matching at the smartfinder. Depending on the application this pre-filtering may enhance detection stability and speed.

The function should be used between the edge() call and the call of the function vc_sf_match_image().

vc_sf_pre_mask_small_regions() is a macro which calls vc_image_fill_small_regions().

Parameters

imgIn	Input Edge Image.
imgOut	Output Edge Image, may be identical to `imgIn`.
minPixel	Pixel areas with less than this count will be filled with zero at the magnitude part of the edge image, and thus not used by the smartfinder.

Function Documentation

◆ vc_sf_init()

I32 vc_sf_init	(	VCSFCfg *	cfg,
		VCSFInit *	init
	)

The function initializes the Smartfinder with given initalisation values.

If you want to add your own initialisation settings, please be sure to first pass default values to the initialisation structure, e.g. the contents of the definition VCSFInit_Default, and afterwards apply your changes:

VCSFCfg   sfCfg  = NULL_VCSFCfg;
VCSFInit  sfInit = VCSFInit_Default;
sfInit.scaleMin = 0.8;
sfInit.scaleMax = 1.2;
rc =  vc_sf_init(&sfCfg, &sfInit);

You can provide NULL as value for init, then default values will be used as being given by VCSFInit_Default.

Parameters

cfg	Smart Finder Configuration.
init	Smart Finder Initialisation Values, or NULL for default values.

Return values

ERR_PARAM	if `rasters` or `patSegments` exceed the maximum allowed value.
ERR_INIT	on failing internal initialisation.
ERR_MEMORY	if memory allocation fails.
ERR_NONE	on success.

See also: vc_sf_deinit().

◆ vc_sf_deinit()

I32 vc_sf_deinit ( VCSFCfg * cfg )

The function deinitializes the Smartfinder.

Parameters

cfg	Smart Finder Settings.

See also: vc_sf_init().

◆ vc_sf_match_image()

I32 vc_sf_match_image	(	image *	vec,
		VCSFPat *	pat,
		VCSFCfg *	cfg,
		VCSFResult *	result
	)

The function matches a smartfinder pattern to similar data in an image. This is the main entry for searching a pattern in an edge image (vector image).

Parameters

vec	The Image to be Searched in, must be of type IMAGE_VECTOR.
pat	Pattern to be Matched.
cfg	Smartfinder Settings, must be initialized beforehand.
result	Result Output.

◆ vc_sf_pattern_from_img()

I32 vc_sf_pattern_from_img	(	image *	vec,
		VCSFPat *	pat,
		VCSFCfg *	cfg
	)

The function generates a smartfinder pattern from a given vector image which then can be used to find similar data in an image. Since the pattern structure is initialized internally, you have to free the pattern when you do not need it anymore by calling the function vc_sf_pattern_free().

Parameters

vec	Source Image of type IMAGE_VECTOR, magnitude 0 marks pattern pixels.
pat	Pattern Output.
cfg	Ahead Initialized Smartfinder Settings.

See also: vc_sf_pattern_from_file(), vc_sf_pattern_from_xylist_I16(), vc_sf_pattern_free().

◆ vc_sf_pattern_from_file()

I32 vc_sf_pattern_from_file	(	char *	path,
		VCSFPat *	pat,
		VCSFCfg *	cfg
	)

The function generates a smartfinder pattern from a previously stored file which then can be used to find similar data in an image. Since the pattern structure is initialized internally, you have to free the pattern after you do not need it anymore by calling the function vc_sf_pattern_free().

Parameters

path	Pattern File to Load.
pat	Pattern Output.
cfg	Ahead Initialized Smartfinder Settings.

See also: vc_sf_pattern_to_file(), vc_sf_pattern_from_img(), vc_sf_pattern_from_xylist_I16(), vc_sf_pattern_free().

Return values

ERR_OPEN if requested file could not be opened for reading.

◆ vc_sf_pattern_from_xylist_I16()

I32 vc_sf_pattern_from_xylist_I16	(	U32	pxCount,
		I16 *	xy,
		U8 *	dir,
		VCSFPat *	pat,
		VCSFCfg *	cfg
	)

The function generates a smartfinder pattern from a given I16 pixel list which then can be used to find similar data in an image. Since the pattern structure is initialized internally, you have to free the pattern after you do not need it anymore by calling the function vc_sf_pattern_free().

IMPORTANT: The xy-list must be lexicographically sorted, i.e. all pixels must be sorted top-down for y and left-to-right for x like the raster scan of a CRT.

Parameters

pxCount	Number of Pixels for the xy-list.
xy,dir	Source pixels and its directions.
pat	Pattern Output.
cfg	Pre-initialized Smartfinder Settings.

See also: vc_sf_pattern_from_file(), vc_sf_pattern_from_img(), vc_sf_pattern_free().

◆ vc_sf_pattern_to_file()

I32 vc_sf_pattern_to_file	(	char *	path,
		VCSFPat *	pat
	)

The function writes a smartfinder pattern to a file which then can be loaded by the function vc_sf_pattern_from_file().

Parameters

path	Pattern File to Store to.
pat	Pattern Input.

See also: vc_sf_pattern_from_file().

Return values

ERR_OPEN if requested file could not be opened for writing.

◆ vc_sf_pattern_free()

I32 vc_sf_pattern_free ( VCSFPat * pat )

The function frees memory allocated for a loaded/teached pattern structure.

Parameters

pat	Pattern to be freed.

See also: vc_sf_pattern_from_file().; vc_sf_pattern_from_img().

◆ vc_sf_searchimagepattern_generate()

I32 vc_sf_searchimagepattern_generate	(	VCSFPat *	patImg,
		image *	vec,
		VCSFCfg *	cfg
	)

This function generates a smartfinder pattern from the vector image wherein other patterns should be found. Since the pattern structure is initialized internally, you have to free the pattern when you do not need it anymore by calling the function vc_sf_pattern_free().

Note: Search patterns should not be generated with this function! Meaningful use of this function is only by combination with the function vc_sf_match_patterns(), see its documentation.

Parameters

vec	Source Image of type IMAGE_VECTOR.
pat	Pattern Output.
cfg	Smartfinder Settings, must be initialized beforehand.

See also: vc_sf_match_image(), vc_sf_pattern_from_img().

◆ vc_sf_match_patterns()

I32 vc_sf_match_patterns	(	VCSFPat *	patImg,
		VCSFPat *	pat,
		VCSFCfg *	cfg,
		VCSFResult *	result
	)

The function matches a smartfinder search pattern to a search image pattern. The Search Image Pattern patImg must be generated using the function vc_sf_searchimagepattern_generate() while the patterns to be searched must be generated using the function vc_sf_pattern_from_img() or another function starting with vc_sf_pattern_from_..().

If only one pattern has to be matched see vc_sf_match_image() instead. To search for more than one pattern utilize this function in the following manner:

I32  my_multi_match(image *vecImgIn, VCSFPat *pat1, VCSFPat *pat2, VCSFCfg *cfg, VCSFResult *result1, VCSFResult *result2)
{
    I32      rc, ee;
    VCSFPat  patImg = NULL_VCSFPat;
    rc =  vc_sf_searchimagepattern_generate(&patImg, vecImgIn, cfg);
    if(rc<0){ee=-1+10*rc;goto fail;}
    rc =  vc_sf_match_patterns(&patImg, &pat1, cfg, result1);
    if(rc<0){ee=-2+10*rc;goto fail;}
    rc =  vc_sf_match_patterns(&patImg, &pat2, cfg, result2);
    if(rc<0){ee=-3+10*rc;goto fail;}
    ee=0;
fail:
    vc_sf_pattern_deinit(&patImg);
    return(ee);
}

Parameters

patImg	Search Image Pattern (vc_sf_searchimagepattern_generate()).
pat	Pattern to be found at the Search Image (e.g. vc_sf_pattern_from_file()).
cfg	Smartfinder Settings, must be initialized beforehand.
result	Result Output.

See also: vc_sf_match_image(), vc_sf_searchimagepattern_generate(), vc_sf_pattern_from_img().

Smart Finder

Data Structures

Macros

Functions

Detailed Description

Data Structure Documentation

◆ VCSFInit

◆ VCSFCfg

◆ VCSFPat

◆ VCSFResult

Macro Definition Documentation

◆ VCSFInit_Default

◆ vc_sf_pre_mask_small_regions

Function Documentation

◆ vc_sf_init()

◆ vc_sf_deinit()

◆ vc_sf_match_image()

◆ vc_sf_pattern_from_img()

◆ vc_sf_pattern_from_file()

◆ vc_sf_pattern_from_xylist_I16()

◆ vc_sf_pattern_to_file()

◆ vc_sf_pattern_free()

◆ vc_sf_searchimagepattern_generate()

◆ vc_sf_match_patterns()