Search Functions

Functions
char *	CLFComment (CLF handle)
	Returns a pointer to the classifier's comment string. More...
const wchar_t *	CLFCommentW (CLF handle)
	Returns a pointer to the classifier's comment string. More...
char *	CLFCreationDate (CLF handle)
	Returns a pointer to the string representation of the classifier's creation date. More...
const wchar_t *	CLFCreationDateW (CLF handle)
	Returns a pointer to the string representation of the classifier's creation date. More...
char *	CLFMTSName (CLF handle)
	Returns a pointer to the name of the MTS (training set) file from which a classifier has been created as passed to LearnCLFFromMTS or LearnCLFFromMTSW. More...
const wchar_t *	CLFMTSNameW (CLF handle)
	Returns a pointer to the name of the MTS (training set) file from which a classifier has been created as passed to LearnCLFFromMTS or LearnCLFFromMTSW. More...
cvbbool_t	CLFSetGlobalAdvance (CLF inputCLF, cvbdim_t dX, cvbdim_t dY, CLF &outputCLF)
	Creates a new classifier in which the advance vectors for all models from the inputCLF have been updated. More...
cvbbool_t	CLFToMemory (CLF handle, void *memory, size_t capacity)
	Serialize a Minos classifier into a memory buffer. More...
cvbbool_t	CLFTransform (CLF inputCLF, TMatrix matrix, CLF &outputCLF)
	Creates a new classifier that is the result of a geometric transformation of the input classifier. More...
cvbbool_t	DuplicateCLF (CLF input, CLF &output)
	Creates a clone of a classifier. More...
cvbbool_t	GetCLFExtent (CLF handle, cvbdim_t &extentLeft, cvbdim_t &extentTop, cvbdim_t &extentRight, cvbdim_t &extentBottom)
	This function returns the extent of the classifier. More...
cvbbool_t	GetCLFLCS (CLF handle, TLearnControlStructure &lcs)
	Retrieves the TLearnControlStructure that has been used for creating a classifier. More...
cvbbool_t	GetCLFModelData (CLF handle, cvbval_t index, char *&pstrName, cvbdim_t &advanceX, cvbdim_t &advanceY)
	Queries the model data as stored in the classifier. More...
cvbbool_t	GetCLFModelDataW (CLF handle, cvbval_t index, wchar_t *&pstrName, cvbdim_t &advanceX, cvbdim_t &advanceY)
	Queries the model data as stored in the classifier. More...
cvbbool_t	GetCLFQualityType (CLF handle, QualityMeasureMethod &method)
	Retrieves the currently set quality measure on a classifier. More...
intptr_t	GetCLFSize (CLF handle)
	Query the memory consumption of a classifier. More...
cvbbool_t	GetCLFThreshold (CLF handle, double &threshold)
	Queries the quality threshold for pattern recognition on a classifier. More...
cvbbool_t	GetCLFTrigger (CLF handle, cvbval_t &trigger)
	Retrieves the currently set contrast trigger threshold on a Minos classifier. More...
cvbbool_t	IsCLF (CLF handle)
	Verifies whether a handle refers to a valid Minos classifier. More...
cvbbool_t	IsOldCLF (CLF handle)
	Indicates if a classifier was created with the 16 bit version of Minos. More...
cvbbool_t	IsResults (RESULTS handle)
	Verifies whether a handle refers to a valid Minos result list. More...
cvbbool_t	LoadCLFFile (const char *pstrFileName, CLF &clf)
	Loads a Minos classifier from a file. More...
cvbbool_t	LoadCLFFileW (const wchar_t *pstrFileName, CLF &clf)
	Loads a Minos classifier from a file. More...
cvbbool_t	MemoryToCLF (void *memory, cvbval_t capacity, CLF &clf)
	Deserialize a classifier that was previously serialized with CLFToMemory. More...
cvbval_t	NumCLFModels (CLF handle)
	Returns the number of different pattern models, for which the classifier was trained. More...
cvbbool_t	ReadCharacterList (CLF handle, IMG image, cvbdim_t index, cvbdensity_t density, TArea area, TArea translatedArea, cvbval_t maxSearch, RESULTS &results)
	Reads a list of characters using the advance vector feature. More...
cvbbool_t	ReadToken (CLF handle, IMG image, cvbdim_t index, cvbdensity_t density, TArea area, TArea translatedArea, cvbval_t maxSearch, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName, cvbval_t &charCount, char *pstrToken)
	Quickly reads a contiguous string or series of objects. More...
cvbbool_t	ReadTokenFirst (CLF handle, IMG image, cvbdim_t index, cvbdensity_t density, TArea area, TArea translatedArea, cvbval_t maxSearch, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName, cvbval_t &charCount, char *pstrToken)
	Quickly reads a contiguous string or series of objects. More...
cvbbool_t	ReadTokenFirstW (CLF handle, IMG image, cvbdim_t index, cvbdensity_t density, TArea area, TArea translatedArea, cvbval_t maxSearch, double &quality, double &xPos, double &yPos, double &dX, double &dY, wchar_t *&pstrName, cvbval_t &charCount, wchar_t *pstrToken)
	Quickly reads a contiguous string or series of objects. More...
cvbbool_t	ReadTokenW (CLF handle, IMG image, cvbdim_t index, cvbdensity_t density, TArea area, TArea translatedArea, cvbval_t maxSearch, double &quality, double &xPos, double &yPos, double &dX, double &dY, wchar_t *&pstrName, cvbval_t &charCount, wchar_t *pstrToken)
	Quickly reads a contiguous string or series of objects. More...
cvbbool_t	ReadVerifyToken (CLF handle, IMG image, cvbdim_t index, cvbdensity_t density, TArea area, TArea translatedArea, cvbval_t maxSearch, RESULTS &results)
	Reads a list of characters using the advance vector feature. More...
cvbbool_t	ReleaseClf (CLF &handle)
	This function releases (decreases the reference counter) of a CLF object. More...
cvbbool_t	ReleaseResults (RESULTS &handle)
	This function releases (decreases the reference counter) of a RESULTS object. More...
cvbbool_t	SearchAll (CLF clf, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, cvbdim_t radius, cvbval_t maxSearch, RESULTS &results)
	Scans the search area for all occurrences of patterns of models trained in the Minos classifier clf. More...
cvbbool_t	SearchFirst (CLF clf, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName)
	Scans the search area for the first pattern that corresponds to one of the models trained in the Minos classifier clf. More...
cvbbool_t	SearchFirstW (CLF clf, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, double &quality, double &xPos, double &yPos, double &dX, double &dY, wchar_t *&pstrName)
	Scans the search area for the first pattern that corresponds to one of the models trained in the Minos classifier clf. More...
cvbbool_t	SearchOptimum (CLF clf, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName)
	Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf. More...
cvbbool_t	SearchOptimumW (CLF handle, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, double &quality, double &xPos, double &yPos, double &dX, double &dY, wchar_t *&pstrName)
	Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf. More...
cvbbool_t	SearchResult (RESULTS handle, cvbdim_t index, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName, cvbval_t &searchID)
	This function reads an entry from a list of search results. More...
cvbval_t	SearchResultsCount (RESULTS handle)
	Returns the number of entries in a RESULTS list. More...
cvbbool_t	SearchResultW (RESULTS handle, cvbdim_t index, double &quality, double &xPos, double &yPos, double &dX, double &dY, wchar_t *&pstrName, cvbval_t &searchID)
	This function reads an entry from a list of search results. More...
cvbbool_t	SetCLFComment (CLF handle, const char *pstrComment)
	Sets the comment string associated on a classifier. More...
cvbbool_t	SetCLFCommentW (CLF handle, const wchar_t *pstrComment)
	Sets the comment string associated on a classifier. More...
cvbbool_t	SetCLFModelData (CLF handle, cvbval_t index, const char *pstrName, cvbdim_t advanceX, cvbdim_t advanceY)
	This function sets model data in the given classifier. More...
cvbbool_t	SetCLFModelDataW (CLF handle, cvbval_t index, const wchar_t *pstrName, cvbdim_t advanceX, cvbdim_t advanceY)
	This function sets model data in the given classifier. More...
cvbbool_t	SetCLFQualityType (CLF handle, QualityMeasureMethod method)
	Sets the quality norm for pattern recognition with a classifier. More...
cvbbool_t	SetCLFThreshold (CLF handle, double threshold)
	Sets the quality threshold for pattern recognition on a classifier. More...
cvbbool_t	SetCLFTrigger (CLF handle, cvbval_t trigger)
	Sets the minimum required contrast for pattern recognition with the classifier. More...
cvbbool_t	ShareClf (CLF handle)
	Increments the reference count for a CLF object. More...
cvbbool_t	ShareResults (RESULTS handle)
	Increments the reference count for a RESULTS object. More...
cvbbool_t	SortResultsByName (RESULTS handle)
	Sorts a list of search results, as created by the functions SearchAll or ReadCharacterList alphabetically by class ID. More...
cvbbool_t	SortResultsByPosition (RESULTS handle, double projectionX, double projectionY)
	Sorts a list of search results, as created by the functions SearchAll, ReadCharacterList or OptCorrelations along a definable vector. More...
cvbbool_t	SortResultsByQuality (RESULTS handle)
	Sorts a list of search results, as created by the functions SearchAll, ReadCharacterList or OptCorrelations by decreasing order of quality. More...
cvbbool_t	SubpixelOptimum (CLF handle, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, double &quality, double &xPos, double &yPos, double &dX, double &dY, char *&pstrName)
	Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf and returns its position with sub pixel accuracy. More...
cvbbool_t	SubpixelOptimumW (CLF handle, IMG img, cvbdim_t index, cvbdensity_t density, TArea area, double &quality, double &xPos, double &yPos, double &dX, double &dY, wchar_t *&pstrName)
	Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf and returns its position with sub pixel accuracy. More...
cvbbool_t	TruncateResults (RESULTS handle, cvbval_t numEntries)
	Truncate a list of search results. More...
cvbbool_t	WriteCLFFile (CLF handle, const char *pstrFileName)
	Stores a Minos classifier in a file. More...
cvbbool_t	WriteCLFFileEx (CLF handle, const char *pstrFileName, TMinosCharacterEncoding encoding)
	Stores a Minos classifier with selectable string encoding in a file. More...
cvbbool_t	WriteCLFFileExW (CLF handle, const wchar_t *pstrFileName, TMinosCharacterEncoding encoding)
	Stores a Minos classifier with selectable string encoding in a file. More...
cvbbool_t	WriteCLFFileW (CLF handle, const wchar_t *pstrFileName)
	Stores a Minos classifier in a file. More...

Detailed Description

Function Documentation

CLFComment()

char * CLFComment

(

CLF

handle

)

Returns a pointer to the classifier's comment string.

The comment string is a read- and writable property of each Minos classifier and may be used for storing custom information inside the classifier.

Parameters

[in]

handle

Handle of the Minos classifier to be queried.

Returns

Pointer to the classifier's comment string if handle refers to a valid Minos classifier, nullptr otherwise.
Note that if the comment contains characters that are not printable with the process's current code page, these characters will be returned as ?.
The returned pointer is a pointer to an internal string in the classifier which means:

• you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this
• the pointer must not be used to write to that string; only read access is acceptable
• once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

See also

SetCLFComment, SetCLFCommentW, CLFCommentW

CLFCommentW()

const wchar_t * CLFCommentW

(

CLF

handle

)

Returns a pointer to the classifier's comment string.

The comment string is a read- and writable property of each Minos classifier and may be used for storing custom information inside the classifier.

Since

Common Vision Blox 13.00.000

Parameters

[in]

handle

Handle of the Minos classifier to be queried.

Returns

Pointer to the classifier's comment string if handle refers to a valid Minos classifier, nullptr otherwise.
The returned pointer is a pointer to an internal string in the classifier which means:

• you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this
• the pointer must not be used to write to that string; only read access is acceptable
• once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

See also

SetCLFComment, SetCLFCommentW, CLFComment

CLFCreationDate()

char * CLFCreationDate

(

CLF

handle

)

Returns a pointer to the string representation of the classifier's creation date.

The creation date string is defined by the system time at the moment LearnCLFFromMTS or LearnCLFFromMTSW has been called for generating the classifier. The date format invariably is mm/dd/yyyy hh:mm:ss AM|PM.

Parameters

[in]

handle

Handle to the Minos classifier for which to query the creation date string.

Returns

Pointer to the classifier's creation date string if handle refers to a valid Minos classifier, nullptr otherwise.
The returned pointer is a pointer to an internal string in the classifier which means:

• you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this
• the pointer must not be used to write to that string; only read access is acceptable
• once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

CLFCreationDateW()

const wchar_t * CLFCreationDateW

(

CLF

handle

)

Returns a pointer to the string representation of the classifier's creation date.

The creation date string is defined by the system time at the moment LearnCLFFromMTS or LearnCLFFromMTSW has been called for generating the classifier. The date format invariably is mm/dd/yyyy hh:mm:ss AM|PM.

Since

Common Vision Blox 13.00.000

Parameters

[in]

handle

Handle to the Minos classifier for which to query the creation date string.

Returns

Pointer to the classifier's creation date string if handle refers to a valid Minos classifier, nullptr otherwise.
The returned pointer is a pointer to an internal string in the classifier which means:

• you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this
• the pointer must not be used to write to that string; only read access is acceptable
• once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

CLFMTSName()

char * CLFMTSName

(

CLF

handle

)

Returns a pointer to the name of the MTS (training set) file from which a classifier has been created as passed to LearnCLFFromMTS or LearnCLFFromMTSW.

The content of the string returned by CLFMTSName is specified in the pstrMTSName parameter of the call to LearnCLFFromMTS or LearnCLFFromMTSW. It becomes an immutable property of the classifier. As the string is defined by the caller of LearnCLFFromMTS or LearnCLFFromMTSW it may of course be used for any kind of static information to be stored in the classifier, and it is only by convention that it is supposed to contain the training set's (file) name.

Parameters

[in]

handle

Handle to the Minos classifier for which to query the MTS name string.

Returns

Pointer to the classifier's MTS name string if handle refers to a valid Minos classifier, nullptr otherwise.
Note that if the string contains characters that are not printable with the process's current code page, these characters will be returned as ?.
The returned pointer is a pointer to an internal string in the classifier which means:

• you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this
• the pointer must not be used to write to that string; only read access is acceptable
• once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

CLFMTSNameW()

const wchar_t * CLFMTSNameW

(

CLF

handle

)

Returns a pointer to the name of the MTS (training set) file from which a classifier has been created as passed to LearnCLFFromMTS or LearnCLFFromMTSW.

The content of the string returned by CLFMTSName is specified in the pstrMTSName parameter of the call to LearnCLFFromMTS or LearnCLFFromMTSW. It becomes an immutable property of the classifier. As the string is defined by the caller of LearnCLFFromMTS or LearnCLFFromMTSW it may of course be used for any kind of static information to be stored in the classifier, and it is only by convention that it is supposed to contain the training set's (file) name.

Since

Common Vision Blox 13.00.000

Parameters

[in]

handle

Handle to the Minos classifier for which to query the MTS name string.

Returns

Pointer to the classifier's MTS name string if handle refers to a valid Minos classifier, nullptr otherwise.
The returned pointer is a pointer to an internal string in the classifier which means:

• you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this
• the pointer must not be used to write to that string; only read access is acceptable
• once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

CLFSetGlobalAdvance()

cvbbool_t CLFSetGlobalAdvance	(	CLF	inputCLF,
		cvbdim_t	dX,
		cvbdim_t	dY,
		CLF &	outputCLF
	)

Creates a new classifier in which the advance vectors for all models from the inputCLF have been updated.

For details about the advance vector feature of Minos please refer to the chapter Guidelines for training font classifiers or the description of the function ReadToken. CLFSetGlobalAdvance sets the advance vector for all models to the same value.

Parameters

[in]	inputCLF	Handle to the input Minos classifier for whose models the advance vectors are to be adjusted.
[in]	dX	X component of the new global advance vector.
[in]	dY	Y component of the new global advance vector.
[out]	outputCLF	Receives the handle to the new Minos classifier with updated advance vectors. Remember to dispose of this classifier with ReleaseObject from the CVCImg.dll once it is no longer needed.

Returns

TRUE if the updated classifier was created successfully, FALSE otherwise. Typical error conditions are:

• inputCLF does not refer to a valid Minos classifier
• an out of memory situation occurred

CLFToMemory()

cvbbool_t CLFToMemory	(	CLF	handle,
		void *	memory,
		size_t	capacity
	)

Serialize a Minos classifier into a memory buffer.

This functionality may be useful for writing a Minos classifier into a settings or configuration file or an application.

Parameters

[in]	handle	Handle to the Minos classifier to be serialized.
[in]	memory	Points to the beginning of the memory block to which the classifier should be serialized.
[in]	capacity	Size of the memory block pointed to by memory available for serialization. Use GetCLFSize to determine the number of bytes necessary. If the block is too small, the function will return FALSE and nothing will be written to the memory block pointed to by memory.

Returns

TRUE if successful, FALSE otherwise. Typical reasons for failure are:

• handle does not pointer to a valid Minos classifier
• no Minos license is available on the system
• capacity is less than the return value of GetCLFSize

See also

MemoryToCLF, GetCLFSize

Example

Serialize a Minos classifier into a block of memory and restore it

// assumptions:
// - clf points to a valid Minos classifier
auto numBytes = GetCLFSize(clf);
if (numBytes <= 0)
  return false;
// note: might as well use malloc() here, but std::vector is self-cleaning
std::vector<uin8_t> buffer(numBytes);
CLFToMemory(clf, buffer.data(), buffer.size());
CLF clf2 = nullptr;
MemoryToCLF(buffer.data(), buffer.size(), clf2);
... // (do something with clf2)
ReleaseObject(clf2);

CLFTransform()

cvbbool_t CLFTransform	(	CLF	inputCLF,
		TMatrix	matrix,
		CLF &	outputCLF
	)

Creates a new classifier that is the result of a geometric transformation of the input classifier.

The transformation needs to be specified as a 2x2 matrix. CLFTransform may be used to adapt an existing classifier to changes in pattern geometry that the classifier has not been trained on. For example, if the objects that the classifier has been trained on appear at only 75% of their original size in an image, the classifier (expecting the patterns at their original size) won't be able to recognize the objects any more.

Transforming the classifier with the matrix

will generate a new classifier rescaled to be able to recognize the trained objects at the reduced scale. Likewise it is possible to rotate a classifier (create the matrix with RotationMatrix from CVCImg.dll in that case) so that it is capable of recognizing objects in rotation states that have not been trained into the classifier.

Even with OCR applications this function may prove useful. Consider a scenario where a font has been trained upright, but should also be read in italics. With some fonts the transition from normal to italics is achieved by tilting the characters slightly by a small angle α. If that is the case, the matrix

may generate a classifier that is capable of reading the tilted version of the characters as well.

Parameters

[in]	inputCLF	Handle to the Minos classifier to be transformed.
[in]	matrix	2x2 transformation matrix to be applied.
[out]	outputCLF	Receives the handle to the new transformed Minos classifier. Remember to dispose of this classifier with ReleaseObject from the CVCImg.dll once it is no longer needed.

Returns

TRUE if the transformed classifier was created successfully, FALSE otherwise. Typical error conditions are:

• inputCLF does not refer to a valid Minos classifier
• an out of memory situation occurred

See also

Rotation or size-independent classifiers, MTSTransform

DuplicateCLF()

cvbbool_t DuplicateCLF	(	CLF	input,
		CLF &	output
	)

Creates a clone of a classifier.

DuplicateCLF uses the function CLFToMemory and MemoryToCLF for creating a clone/deep copy of the input classifier. The resulting output classifier is a completely independent copy of the input.

Parameters

[in]	input	Minos classifier to be cloned.
[out]	output	Will receive the handle to the cloned classifier. Remember to call ReleaseObject on it once it is no longer needed.

Returns

TRUE if the classifier was successfully cloned, FALSE if an error occurs. Possible reasons for failure are:

• input does not refer to a valid Minos classifier
• an out of memory condition occurred while cloning the classifier

See also

CLFToMemory, GetCLFSize, MemoryToCLF

GetCLFExtent()

cvbbool_t GetCLFExtent	(	CLF	handle,
		cvbdim_t &	extentLeft,
		cvbdim_t &	extentTop,
		cvbdim_t &	extentRight,
		cvbdim_t &	extentBottom
	)

This function returns the extent of the classifier.

The extent (sometimes also called feature window) of a classifier is defined as the smallest rectangle which the classifier requires to classify the point (x,y). An extent of (-5, -7, 20, 30) for example means that the classifier needs to look 5 pixels to the left, 7 pixels above, 20 pixels to the right and 30 pixels below the point (x,y).

For a classifier with more than just one model the extent is the union of the extents of all models in the classifier.

Parameters

[in]	handle	Handle to the Minos classifier.
[out]	extentLeft	Left extent.
[out]	extentTop	Top extent.
[out]	extentRight	Right extent.
[out]	extentBottom	Bottom extent.

Returns

TRUE if the extent was queried successfully, FALSE if handle does not refer to a valid Minos classifier.

GetCLFLCS()

cvbbool_t GetCLFLCS	(	CLF	handle,
		TLearnControlStructure &	lcs
	)

Retrieves the TLearnControlStructure that has been used for creating a classifier.

Note that the members Data and ShowProgress of the returned struct will always contain null pointers.

Parameters

[in]	handle	Handle to the Minos classifier to be queried.
[out]	lcs	Receives the TLearnControlStructure with which the classifier referenced by handle has been trained.

Returns

TRUE if the data was queried successfully, FALSE otherwise (in this case handle does not refer to a valid Minos classifier).

GetCLFModelData()

cvbbool_t GetCLFModelData	(	CLF	handle,
		cvbval_t	index,
		char *&	pstrName,
		cvbdim_t &	advanceX,
		cvbdim_t &	advanceY
	)

Queries the model data as stored in the classifier.

The model for which information should be retrieved is referred to by an index ranging from zero to the number returned by NumCLFModels.

Parameters

[in]	handle	Handle to the Minos classifier for which to query model data.
[in]	index	Index of the model for which to query the data. Must be in the range [0...NumCLFModels(handle)-1].
[out]	pstrName	Receives a pointer to the model name. Note that if the model name contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	advanceX	X component of the advance vector.
[out]	advanceY	Y component of the advance vector.

Returns

TRUE if the model data were queried successfully, FALSE otherwise. Typical error conditions are:

• handle does not refer to a valid Minos classifier.
• index is outside the range [0...NumCLFModels(handle)-1].

See also

SetCLFModelData, SetCLFModelDataW, GetCLFModelDataW

GetCLFModelDataW()

cvbbool_t GetCLFModelDataW	(	CLF	handle,
		cvbval_t	index,
		wchar_t *&	pstrName,
		cvbdim_t &	advanceX,
		cvbdim_t &	advanceY
	)

Queries the model data as stored in the classifier.

The model for which information should be retrieved is referred to by an index ranging from zero to the number returned by NumCLFModels - 1.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier for which to query model data.
[in]	index	Index of the model for which to query the data. Must be in the range [0...NumCLFModels(handle)-1].
[out]	pstrName	Receives a pointer to the model name. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	advanceX	X component of the advance vector.
[out]	advanceY	Y component of the advance vector.

Returns

TRUE if the model data were queried successfully, FALSE otherwise. Typical error conditions are:

• handle does not refer to a valid Minos classifier.
• index is outside the range [0...NumCLFModels(handle)-1].

See also

SetCLFModelData, SetCLFModelDataW, GetCLFModelData

GetCLFQualityType()

cvbbool_t GetCLFQualityType	(	CLF	handle,
		QualityMeasureMethod &	method
	)

Retrieves the currently set quality measure on a classifier.

The quality of a Minos search result may be measured in one of two different ways:

• normalized (Quality_ReturnCorrelation) by calculating the correlation between the pixels available at the result location versus those from the trained features
• unnormalized (Quality_Unnormalized) by calculating the average contrast encountered during a search operation

Parameters

[in]	handle	Handle to the Minos classifier to be queried.
[out]	method	Currently selected quality type. See QualityMeasureMethod for an interpretation of the returned value.

Returns

TRUE if the method has been set successfully, FALSE otherwise (in this case handle does not refer to a valid Minos classifier).

See also

QualityMeasureMethod, SetCLFQualityType

GetCLFSize()

intptr_t GetCLFSize

(

CLF

handle

)

Query the memory consumption of a classifier.

This function returns the number of bytes required for serializing the classifier referred to by handle. This information is required for the function CLFToMemory.

Parameters

[in]

handle

Handle to the Minos classifier.

Returns

If the function call is successful the serialized size of the classifier will be returned. In case of an error (handle does not refer to a valid classifier) -1 will be returned.

See also

CLFToMemory

GetCLFThreshold()

cvbbool_t GetCLFThreshold	(	CLF	handle,
		double &	threshold
	)

Queries the quality threshold for pattern recognition on a classifier.

The Threshold specifies the minimum quality that a result must achieve before being reported by any of the search functions that a Minos classifier might be used with. Note that the threshold is measured in terms of the classifier's currently selected quality type (see SetCLFQualityType/GetCLFQualityType).

Parameters

[in]	handle	Handle to the Minos classifier on which to query the threshold.
[out]	threshold	Currently set quality threshold.

Returns

TRUE if the threshold has been set successfully (in this case handle does not refer to a valid Minos classifier), FALSE otherwise.

See also

SetCLFThreshold, GetCLFQualityType, SetCLFQualityType

GetCLFTrigger()

cvbbool_t GetCLFTrigger	(	CLF	handle,
		cvbval_t &	trigger
	)

Retrieves the currently set contrast trigger threshold on a Minos classifier.

The trigger specifies the minimum contrast amplitude required for the feature verification of Minos to respond. The default value is the one that has been used when generating the classifier (specified in the TLearnControlStructure, recommended is a value of 8 here).

Parameters

[in]	handle	Handle to the Minos classifier for which to query the contrast trigger value.
[out]	trigger	Currently set contrast trigger threshold.

Returns

TRUE if the contrast trigger was queried successfully, FALSE otherwise (in that case handle does not seem to refer to a valid Minos classifier.

See also

SetCLFTrigger

IsCLF()

cvbbool_t IsCLF

(

CLF

handle

)

Verifies whether a handle refers to a valid Minos classifier.

Use this function with a given handle to determine whether or not it refers to a valid Minos classifier.

Parameters

[in]

handle

Handle to be checked.

Returns

TRUE (non-zero value) if handle refers to a valid Minos classifier, FALSE otherwise.

See also

IsResults, IsMTS, IsMTSImage, IsMTSInstance, IsMTSModel

IsOldCLF()

cvbbool_t IsOldCLF

(

CLF

handle

)

Indicates if a classifier was created with the 16 bit version of Minos.

Classifiers generated with the 16 bit versions of Minos are restricted in their capabilities (no support for sub pixel accurate position measurement; no support for correlation-based quality feedback), therefore during the transition from 16 to 32 bit it was important to have a means of checking what type of classifier was being used.

Today, the 16 bit Minos classifiers are not really relevant any more and the new builds of Minos are not actually checked any longer for compatibility with 16 bit classifiers. Therefore use of IsOldCLF has been declared deprecated.

Parameters

[in]

handle

Handle to the Minos classifier to be queried.

Returns

The function returns TRUE if the handle refers to an old Minos classifier created with the 16 bit version of Minos. It returns FALSE if handle does not refer to a valid Minos classifier or if the Minos classifier referred to by handle has not been generated with a 16 bit version of Minos.

IsResults()

cvbbool_t IsResults

(

RESULTS

handle

)

Verifies whether a handle refers to a valid Minos result list.

Use this function with a given handle to determine whether or not it refers to a valid Minos result list.

Parameters

[in]

handle

Handle to be checked.

Returns

TRUE (non-zero value) if handle refers to a valid Minos result list, FALSE otherwise.

See also

IsCLF, IsMTS, IsMTSImage, IsMTSInstance, IsMTSModel

LoadCLFFile()

cvbbool_t LoadCLFFile	(	const char *	pstrFileName,
		CLF &	clf
	)

Loads a Minos classifier from a file.

If the function succeeds, the handle returned in the clf parameter will point to the newly loaded Minos classifier. All Minos classifiers 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 classifier by calling ReleaseObject on it once it is no longer needed.

Note that this function will be able to load the classifier regardless of whether it has been saved with Common Vision Blox 13.00.000 or higher (i.e. potentially with UTF8 encoding) or an older version (with ASCII encoding).

Parameters

[out]	clf	If loading the classifier succeeded, this parameter will receive the handle to the Minos classifier.
[in]	pstrFileName	Name of the file from which to load the classifier.

Returns

TRUE (non-zero value) on success, FALSE (0) otherwise.

See also

LoadCLFFileW, WriteCLFFile, WriteCLFFileEx, WriteCLFFileExW, WriteCLFFileEx

LoadCLFFileW()

cvbbool_t LoadCLFFileW	(	const wchar_t *	pstrFileName,
		CLF &	clf
	)

Loads a Minos classifier from a file.

If the function succeeds, the handle returned in the clf parameter will point to the newly loaded Minos classifier. All Minos classifiers 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 classifier by calling ReleaseObject on it once it is no longer needed.

Note that this function will be able to load the classifier regardless of whether it has been saved with Common Vision Blox 13.00.000 or higher (i.e. potentially with UTF8 encoding) or an older version (with ASCII encoding).

Since

Common Vision Blox 13.00.000

Parameters

[out]	clf	If loading the classifier succeeded, this parameter will receive the handle to the Minos classifier.
[in]	pstrFileName	Name of the file from which to load the classifier.

Returns

TRUE (non-zero value) on success, FALSE (0) otherwise.

See also

LoadCLFFile, WriteCLFFile, WriteCLFFileEx, WriteCLFFileExW, WriteCLFFileEx

MemoryToCLF()

cvbbool_t MemoryToCLF	(	void *	memory,
		cvbval_t	capacity,
		CLF &	clf
	)

Deserialize a classifier that was previously serialized with CLFToMemory.

For all intents and purposes this is the inverse function for CLFToMemory. See the description of CLFToMemory for a usage example.

Parameters

[in]	memory	Memory buffer containing the serialized classifier.
[in]	capacity	Size of the serialized classifier.
[out]	clf	Will receive the handle to the deserialized classifier. Remember to call ReleaseObject on it once it is no longer needed.

Returns

TRUE if the classifier was successfully deserialized, FALSE if an error occurs. Possible reasons for failure are:

• memory is a nullptr
• capacity is less than or equal to zero
• the buffer pointed to by memory does not contain a serialized classifier.

See also

CLFToMemory, GetCLFSize

NumCLFModels()

cvbval_t NumCLFModels

(

CLF

handle

)

Returns the number of different pattern models, for which the classifier was trained.

Note that different models with identical names are still counted as individual models.

Parameters

[in]

handle

Handle to the Minos classifier.

Returns

Number of different pattern models in the classifier or -1 if handle does not refer to a valid Minos classifier.

ReadCharacterList()

cvbbool_t ReadCharacterList	(	CLF	handle,
		IMG	image,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		TArea	translatedArea,
		cvbval_t	maxSearch,
		RESULTS &	results
	)

Reads a list of characters using the advance vector feature.

ReadCharacterList does essentially the same as ReadToken (and for a detailed description about the advance vector feature and its use in OCR operation please refer to the description of ReadToken.

The difference between ReadCharacterList and ReadToken is that while ReadToken returns the concatenated string over all the results it encountered along with the results pertaining to the last encountered character/object, ReadCharacterList will assemble a RESULTS list of the individual results and return this to the caller. This result list may then be processed using the functions SearchResultsCount and SearchResult/SearchResultW (see also the description of SearchAll, which also returns such a list).

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	handle	Handle of the Minos classifier to be used.
[in]	image	Handle of the image to use the classifier on.
[in]	index	Index of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]	density	Scan density to apply when searching for the next character. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area of interest in which to searched for the 1st character character in the string. Usually this area will be comparatively small and is best determined using a priori knowledge and/or SearchFirst (see e.g. the Minos VC OCR example's source code or the example below).
[in]	translatedArea	Expectation window relative to the tip of the previous model's advance vector in which to look for the subsequent character. As translatedArea is given relative to the tip of the previous model's advance vector it is usually given with very small, partly negative positions (see example below).
[in]	maxSearch	Maximal number of results to gather. Defines the upper limit for the size of the list returned in results;
[out]	results	List of result patterns that has been found. Use the functions IsResults, SearchResultsCount, SearchResult and SearchResultW to query that list (see code example further down). Once the result list is no longer needed it needs to be disposed of with a call to the ReleaseObject function from the CVCImg.dll.

Returns

TRUE if the search was successful, FALSE otherwise. Typical reasons for failure are:

• handle does not point to a valid Minos classifier
• image does not refer to a valid Common Vision Blox image
• index was not from the range [0...ImageDimension(image)-1] -maxSearch` was less than 1

See also

ReadTokenW, ReadToken, ReadCharacterList, ReadTokenFirst, SearchFirst, SearchFirstW, Testing OCR Classifiers

ReadToken()

cvbbool_t ReadToken	(	CLF	handle,
		IMG	image,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		TArea	translatedArea,
		cvbval_t	maxSearch,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		char *&	pstrName,
		cvbval_t &	charCount,
		char *	pstrToken
	)

Quickly reads a contiguous string or series of objects.

ReadToken uses the model-specific advance vector (sometimes also called 'OCR-vector') to read contiguous sequences of characters or objects efficiently. The advance vector is a vector that is anchored at a model's anchor or focus point and is supposed to point to the position at which the next character is to be expected (for a given character the presumable position of the following character is, after all, defined mostly by the character's width; consequently, the advance vector is by default set to the initial width of the model as specified during training).

This a priori knowledge can help speed up the process of reading a string of characters: Once the position of the first character of the string is known, the function ReadToken is able to walk through the string fairly quickly (concatenating the IDs of the encountered models to the result string as it proceeds) because it will only need to consider the translatedArea for the follow-up searches, placed at the tip of the advance vector of the previous model, which greatly reduces the overall amount of pixels to be investigated compared to e.g. a SearchAll call.

(Note how it usually makes sense with latin character sets to place the focal point of the model in the lower left corner of a character's bounding box - that way proportional and fixed-size fonts are easily covered equally well).

A ReadToken will automatically stop once no matching pattern is found in the translatedArea any more (which implicitly means that ReadToken will automatically be interrupted by a whitespace or word boundary).

Note that ReadToken, although tailored to the requirements of optical character recognition (OCR) is not limited to OCR applications. The advance vector mechanism described earlier may - depending on the application's requirements - also be used in other fields like e.g. PCB inspection. If a sequence of unique elements on a PCB is to be checked with a Minos classifier and the elements to be checked always have the same placement on the PCB, the overall inspection time may profit greatly from using the ReadToken functionality.

For an example have a look at the AMVS.mts training set. There, four unique parts (i.e. parts that occur only once on the PCB to be inspected) have been trained with the names 'o', 'k', 'a' and 'y'. Each model has been assigned an advance vector that points to the next model in such manner that the ReadToken reading result when started at the expected left top model 'o' spells out 'okay' - after a fraction of the time a SearchAll call would have taken.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	handle	Handle of the Minos classifier to be used.
[in]	image	Handle of the image to use the classifier on.
[in]	index	Index of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]	density	Scan density to apply when searching for the next character. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area of interest in which to searched for the 1st character character in the string. Usually this area will be comparatively small and is best determined using a priori knowledge and/or SearchFirst (see e.g. the Minos VC OCR example's source code or the example below).
[in]	translatedArea	Expectation window relative to the tip of the previous model's advance vector in which to look for the subsequent character. As translatedArea is given relative to the tip of the previous model's advance vector it is usually given with very small, partly negative positions (see example below).
[in]	maxSearch	Maximal number of characters to read. This parameter effectively gives the size of the buffer pointed to by pstrToken (add 1 for the terminating null character).
[out]	quality	Pattern quality of the last pattern encountered; if no pattern was found, quality will be set to zero.
[out]	xPos	X position of the last pattern found. If no pattern was found, xPos will not be modified.
[out]	yPos	Y position of the last pattern found. If no pattern was found, yPos will not be modified.
[out]	dX	X component of the advance vector of the last pattern found. If no pattern was found, dX will not be modified.
[out]	dY	Y component of the advance vector of the last pattern found. If no pattern was found, dY will not be modified.
[out]	pstrName	Receives a pointer to the class ID of the last pattern found. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	charCount	Number of characters that have been written to the buffer pointed to by pstrName.
[in]	pstrToken	Pointer to a buffer that will receive the read result (which is the concatenated set of class IDs in the sequence in which they were encountered in the image). The string will be zero terminated. The memory pointed to by pstrToken must be at least maxSearch + 1 characters long.

Returns

TRUE if the search was successful, FALSE otherwise. Typical reasons for failure are:

• handle does not point to a valid Minos classifier
• image does not refer to a valid Common Vision Blox image
• index was not from the range [0...ImageDimension(image)-1] -pstrTokenwas anullptr -maxSearch` was less than 1

See also

ReadTokenW, ReadCharacterList, ReadTokenFirst, ReadTokenFirstW, SearchFirst, SearchFirstW, Testing OCR Classifiers

Example

// assumptions:
// - clf refers to a valid Minos classifier
// - img refers to a valid Minos image with at least one line of 
//   characters that have been trained into 'clf'
// - the width of the characters is about 10 pixels, the height about 20
//   pixels
 
// a few variables that will be needed...
double quality, xPos, yPos, dX, dY;
quality = xPos = yPos = dX = dY = 0.0;
char* pstrClass = nullptr;
 
// before reading the string it is necessary to determine its start 
// location in the image. assuming that the string is horizontally 
// oriented and covers at least half the width of the image this is
// fairly straightforward
TArea aoiTopDown;
aoiTopDown.X0 = ImageWidth(img) / 2 - 10;
aoiTopDown.Y0 = 0;
aoiTopDown.X1 = ImageWidth(img) / 2 + 10;
aoiTopDown.Y0 = 0;
aoiTopDown.X2 = aoiTopDown.X0;
aoiTopDown.Y2 = ImageHeight(img) - 1;
SearchFirst(clf, img, 0, 1000, aoiTopDown, quality, 
  xPos, yPos, dX, dY, pstrClass);
if (quality <= 0.0)
{
  std::cout << "vertical line position not found" << std::endl;
  return false;
}
 
// the vertical position of the line has been pinpointed to 'yPos' now;
// the horizontal start now needs to be determined with a differently
// aligned aoi:
TArea aoiLeftRight;
aoiLeftRight.X0 = 0;
aoiLeftRight.Y0 = yPos - 20 / 2;
aoiLeftRight.X1 = 0;
aoiLeftRight.Y1 = yPos + 20 / 2;
aoiLeftRight.X2 = xPos;
aoiLeftRight.Y2 = aoiLeftRight.Y0;
SearchFirst(clf, img, 0, 1000, aoiLeftRight, quality,
  xPos, yPos, dX, dY, pstrClass);
if (quality <= 0.0)
{
  std::cout << "horizontal line position not found" << std::endl;
  return false;
}
 
// line starts at (xPos, yPos) --> now prepare parameters for ReadToken
std::vector<char> buffer(256);
TArea lineStart;
lineStart.X0 = xPos - 1;
lineStart.Y0 = yPos - 1;
lineStart.X1 = xPos + 1;
lineStart.Y1 = lineStart.Y0;
lineStart.X2 = lineStart.X0;
lineStart.Y2 = yPos + 1;
// build the translated aoi as a square 11 pixels high and wide
// ('radius' = 5 in the terminology of the teach program)
TArea translatedAoi;
translatedAoi.X0 = -5;
translatedAoi.Y0 = -5;
translatedAoi.X1 =  5;
translatedAoi.Y1 = -5;
translatedAoi.X2 = -5;
translatedAoi.Y2 =  5;
cvbval_t numCharsRead = 0;
ReadToken(clf, img, 0, 1000, translatedAoi, static_cast<cvbval_t>(buffer.size()),
  quality, xPos, yPos, dX, dY, pstrName, numCharsRead, buffer.data());
if (numCharsRead)
{
  std::cout << "Read: " << buffer.data() << std::endl;
  return true;
}
else
{
  std::cout << "Nothing read." << std::endl;
  return false;
}

ReadTokenFirst()

cvbbool_t ReadTokenFirst	(	CLF	handle,
		IMG	image,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		TArea	translatedArea,
		cvbval_t	maxSearch,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		char *&	pstrName,
		cvbval_t &	charCount,
		char *	pstrToken
	)

Quickly reads a contiguous string or series of objects.

ReadTokenFirst is almost identical in functionality to ReadToken. The only difference is that while ReadToken reports the properties of the last read character in the parameters quality, xPos, yPos, dX, dY and pstrName, ReadTokenFirst instead reports the properties of the first read character.

For a detailed description of how ReadToken (and therefore also ReadTokenFirst works, as well as a example on how to use it please refer to the description of ReadToken.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	handle	Handle of the Minos classifier to be used.
[in]	image	Handle of the image to use the classifier on.
[in]	index	Index of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]	density	Scan density to apply when searching for the next character. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area of interest in which to searched for the 1st character character in the string. Usually this area will be comparatively small and is best determined using a priori knowledge and/or SearchFirst (see e.g. the Minos VC OCR example's source code or the example below).
[in]	translatedArea	Expectation window relative to the tip of the previous model's advance vector in which to look for the subsequent character. As translatedArea is given relative to the tip of the previous model's advance vector it is usually given with very small, partly negative positions (see example below).
[in]	maxSearch	Maximal number of characters to read. This parameter effectively gives the size of the buffer pointed to by pstrToken (add 1 for the terminating null character).
[out]	quality	Pattern quality of the first pattern encountered; if no pattern was found, quality will be set to zero.
[out]	xPos	X position of the first pattern found. If no pattern was found, xPos will not be modified.
[out]	yPos	Y position of the first pattern found. If no pattern was found, yPos will not be modified.
[out]	dX	X component of the advance vector of the first pattern found. If no pattern was found, dX will not be modified.
[out]	dY	Y component of the advance vector of the first pattern found. If no pattern was found, dY will not be modified.
[out]	pstrName	Receives a pointer to the class ID of the first pattern found. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	charCount	Number of characters that have been written to the buffer pointed to by pstrName.
[in]	pstrToken	Pointer to a buffer that will receive the read result (which is the concatenated set of class IDs in the sequence in which they were encountered in the image). The string will be zero terminated. The memory pointed to by pstrToken must be at least maxSearch + 1 characters long.

Returns

TRUE if the search was successful, FALSE otherwise. Typical reasons for failure are:

• handle does not point to a valid Minos classifier
• image does not refer to a valid Common Vision Blox image
• index was not from the range [0...ImageDimension(image)-1] -pstrTokenwas anullptr -maxSearch` was less than 1

See also

ReadTokenW, ReadToken, ReadCharacterList, ReadTokenFirstW, SearchFirst, SearchFirstW, Testing OCR Classifiers

ReadTokenFirstW()

cvbbool_t ReadTokenFirstW	(	CLF	handle,
		IMG	image,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		TArea	translatedArea,
		cvbval_t	maxSearch,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		wchar_t *&	pstrName,
		cvbval_t &	charCount,
		wchar_t *	pstrToken
	)

Quickly reads a contiguous string or series of objects.

ReadTokenFirstW is almost identical in functionality to ReadTokenW. The only difference is that while ReadTokenW reports the properties of the last read character in the parameters quality, xPos, yPos, dX, dY and pstrName, ReadTokenFirst instead reports the properties of the first read character.

For a detailed description of how ReadTokenW (and therefore also ReadTokenFirst works, as well as a example on how to use it please refer to the description of ReadTokenW.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle of the Minos classifier to be used.
[in]	image	Handle of the image to use the classifier on.
[in]	index	Index of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]	density	Scan density to apply when searching for the next character. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area of interest in which to searched for the 1st character character in the string. Usually this area will be comparatively small and is best determined using a priori knowledge and/or SearchFirst (see e.g. the Minos VC OCR example's source code or the example below).
[in]	translatedArea	Expectation window relative to the tip of the previous model's advance vector in which to look for the subsequent character. As translatedArea is given relative to the tip of the previous model's advance vector it is usually given with very small, partly negative positions (see example below).
[in]	maxSearch	Maximal number of characters to read. This parameter effectively gives the size of the buffer pointed to by pstrToken (add 1 for the terminating null character).
[out]	quality	Pattern quality of the first pattern encountered; if no pattern was found, quality will be set to zero.
[out]	xPos	X position of the first pattern found. If no pattern was found, xPos will not be modified.
[out]	yPos	Y position of the first pattern found. If no pattern was found, yPos will not be modified.
[out]	dX	X component of the advance vector of the first pattern found. If no pattern was found, dX will not be modified.
[out]	dY	Y component of the advance vector of the first pattern found. If no pattern was found, dY will not be modified.
[out]	pstrName	Receives a pointer to the class ID of the first pattern found. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	charCount	Number of characters that have been written to the buffer pointed to by pstrName.
[in]	pstrToken	Pointer to a buffer that will receive the read result (which is the concatenated set of class IDs in the sequence in which they were encountered in the image). The string will be zero terminated. The memory pointed to by pstrToken must be at least maxSearch + 1 characters long.

Returns

TRUE if the search was successful, FALSE otherwise. Typical reasons for failure are:

• handle does not point to a valid Minos classifier
• image does not refer to a valid Common Vision Blox image
• index was not from the range [0...ImageDimension(image)-1] -pstrTokenwas anullptr -maxSearch` was less than 1

See also

ReadTokenW, ReadToken, ReadCharacterList, ReadTokenFirst, SearchFirst, SearchFirstW, Testing OCR Classifiers

ReadTokenW()

cvbbool_t ReadTokenW	(	CLF	handle,
		IMG	image,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		TArea	translatedArea,
		cvbval_t	maxSearch,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		wchar_t *&	pstrName,
		cvbval_t &	charCount,
		wchar_t *	pstrToken
	)

Quickly reads a contiguous string or series of objects.

ReadTokenW uses the model-specific advance vector (sometimes also called 'OCR-vector') to read contiguous sequences of characters or objects efficiently. The advance vector is a vector that is anchored at a model's anchor or focus point and is supposed to point to the position at which the next character is to be expected (for a given character the presumable position of the following character is, after all, defined mostly by the character's width; consequently, the advance vector is by default set to the initial width of the model as specified during training).

This a priori knowledge can help speed up the process of reading a string of characters: Once the position of the first character of the string is known, the function ReadTokenW is able to walk through the string fairly quickly (concatenating the IDs of the encountered models to the result string as it proceeds) because it will only need to consider the translatedArea for the follow-up searches, placed at the tip of the advance vector of the previous model, which greatly reduces the overall amount of pixels to be investigated compared to e.g. a SearchAll call.

(Note how it usually makes sense with latin character sets to place the focal point of the model in the lower left corner of a character's bounding box - that way proportional and fixed-size fonts are easily covered equally well).

A ReadTokenW will automatically stop once no matching pattern is found in the translatedArea any more (which implicitly means that ReadTokenW will automatically be interrupted by a whitespace or word boundary).

Note that ReadTokenW, although tailored to the requirements of optical character recognition (OCR) is not limited to OCR applications. The advance vector mechanism described earlier may - depending on the application's requirements - also be used in other fields like e.g. PCB inspection. If a sequence of unique elements on a PCB is to be checked with a Minos classifier and the elements to be checked always have the same placement on the PCB, the overall inspection time may profit greatly from using the ReadTokenW functionality.

For an example have a look at the AMVS.mts training set. There, four unique parts (i.e. parts that occur only once on the PCB to be inspected) have been trained with the names 'o', 'k', 'a' and 'y'. Each model has been assigned an advance vector that points to the next model in such manner that the ReadTokenW reading result when started at the expected left top model 'o' spells out 'okay' - after a fraction of the time a SearchAll call would have taken.

Since

Common Vision Blox 13.00.000

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	handle	Handle of the Minos classifier to be used.
[in]	image	Handle of the image to use the classifier on.
[in]	index	Index of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]	density	Scan density to apply when searching for the next character. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area of interest in which to searched for the 1st character character in the string. Usually this area will be comparatively small and is best determined using a priori knowledge and/or SearchFirst (see e.g. the Minos VC OCR example's source code or the example below).
[in]	translatedArea	Expectation window relative to the tip of the previous model's advance vector in which to look for the subsequent character. As translatedArea is given relative to the tip of the previous model's advance vector it is usually given with very small, partly negative positions (see example below).
[in]	maxSearch	Maximal number of characters to read. This parameter effectively defines the size of the buffer pointed to by pstrToken (add 1 for the terminating null character).
[out]	quality	Pattern quality of the last pattern encountered; if no pattern was found, quality will be set to zero.
[out]	xPos	X position of the last pattern found. If no pattern was found, xPos will not be modified.
[out]	yPos	Y position of the last pattern found. If no pattern was found, yPos will not be modified.
[out]	dX	X component of the advance vector of the last pattern found. If no pattern was found, dX will not be modified.
[out]	dY	Y component of the advance vector of the last pattern found. If no pattern was found, dY will not be modified.
[out]	pstrName	Receives a pointer to the class ID of the last pattern found. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	charCount	Number of characters that have been written to the buffer pointed to by pstrName.
[in]	pstrToken	Pointer to a buffer that will receive the read result (which is the concatenated set of class IDs in the sequence in which they were encountered in the image). The string will be zero terminated. The memory pointed to by pstrToken must be at least maxSearch + 1 characters long.

Returns

TRUE if the search was successful, FALSE otherwise. Typical reasons for failure are:

• handle does not point to a valid Minos classifier
• image does not refer to a valid Common Vision Blox image
• index was not from the range [0...ImageDimension(image)-1] -pstrTokenwas anullptr -maxSearch` was less than 1

See also

ReadToken, ReadCharacterList, ReadTokenFirst, ReadTokenFirstW, SearchFirst, SearchFirstW, Testing OCR Classifiers

Example

// assumptions:
// - clf refers to a valid Minos classifier
// - img refers to a valid Minos image with at least one line of 
//   characters that have been trained into 'clf'
// - the width of the characters is about 10 pixels, the height about 20
//   pixels
 
// a few variables that will be needed...
double quality, xPos, yPos, dX, dY;
quality = xPos = yPos = dX = dY = 0.0;
wchar_t* pstrClass = nullptr;
 
// before reading the string it is necessary to determine its start 
// location in the image. assuming that the string is horizontally 
// oriented and covers at least half the width of the image this is
// fairly straightforward
TArea aoiTopDown;
aoiTopDown.X0 = ImageWidth(img) / 2 - 10;
aoiTopDown.Y0 = 0;
aoiTopDown.X1 = ImageWidth(img) / 2 + 10;
aoiTopDown.Y0 = 0;
aoiTopDown.X2 = aoiTopDown.X0;
aoiTopDown.Y2 = ImageHeight(img) - 1;
SearchFirstW(clf, img, 0, 1000, aoiTopDown, quality, 
  xPos, yPos, dX, dY, pstrClass);
if (quality <= 0.0)
{
  std::wcout << L"vertical line position not found" << std::endl;
  return false;
}
 
// the vertical position of the line has been pinpointed to 'yPos' now;
// the horizontal start now needs to be determined with a differently
// aligned aoi:
TArea aoiLeftRight;
aoiLeftRight.X0 = 0;
aoiLeftRight.Y0 = yPos - 20 / 2;
aoiLeftRight.X1 = 0;
aoiLeftRight.Y1 = yPos + 20 / 2;
aoiLeftRight.X2 = xPos;
aoiLeftRight.Y2 = aoiLeftRight.Y0;
SearchFirstW(clf, img, 0, 1000, aoiLeftRight, quality,
  xPos, yPos, dX, dY, pstrClass);
if (quality <= 0.0)
{
  std::wcout << L"horizontal line position not found" << std::endl;
  return false;
}
 
// line starts at (xPos, yPos) --> now prepare parameters for ReadToken
std::vector<wchar_t> buffer(256);
TArea lineStart;
lineStart.X0 = xPos - 1;
lineStart.Y0 = yPos - 1;
lineStart.X1 = xPos + 1;
lineStart.Y1 = lineStart.Y0;
lineStart.X2 = lineStart.X0;
lineStart.Y2 = yPos + 1;
// build the translated aoi as a square 11 pixels high and wide
// ('radius' = 5 in the terminology of the teach program)
TArea translatedAoi;
translatedAoi.X0 = -5;
translatedAoi.Y0 = -5;
translatedAoi.X1 =  5;
translatedAoi.Y1 = -5;
translatedAoi.X2 = -5;
translatedAoi.Y2 =  5;
cvbval_t numCharsRead = 0;
ReadTokenW(clf, img, 0, 1000, translatedAoi, static_cast<cvbval_t>(buffer.size()),
  quality, xPos, yPos, dX, dY, pstrName, numCharsRead, buffer.data());
if (numCharsRead)
{
  std::wcout << L"Read: " << buffer.data() << std::endl;
  return true;
}
else
{
  std::wcout << "Nothing read." << std::endl;
  return false;
}

ReadVerifyToken()

cvbbool_t ReadVerifyToken	(	CLF	handle,
		IMG	image,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		TArea	translatedArea,
		cvbval_t	maxSearch,
		RESULTS &	results
	)

Reads a list of characters using the advance vector feature.

ReadVerifyToken does essentially the same as ReadToken (and for a detailed description about the advance vector feature and its use in OCR operation please refer to the description of ReadToken.

The difference between ReadVerifyToken and ReadToken is that while ReadToken returns the concatenated string over all the results it encountered along with the results pertaining to the last encountered character/object, ReadVerifyToken will assemble a RESULTS list of the individual results and return this to the caller. This result list may then be processed using the functions SearchResultsCount and SearchResult/SearchResultW (see also the description of SearchAll, which also returns such a list).

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	handle	Handle of the Minos classifier to be used.
[in]	image	Handle of the image to use the classifier on.
[in]	index	Index of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]	density	Scan density to apply when searching for the next character. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area of interest in which to searched for the 1st character character in the string. Usually this area will be comparatively small and is best determined using a priori knowledge and/or SearchFirst (see e.g. the Minos VC OCR example's source code or the example below).
[in]	translatedArea	Expectation window relative to the tip of the previous model's advance vector in which to look for the subsequent character. As translatedArea is given relative to the tip of the previous model's advance vector it is usually given with very small, partly negative positions (see example below).
[in]	maxSearch	Maximal number of results to gather. Defines the upper limit for the size of the list returned in results;
[out]	results	List of result patterns that has been found. Use the functions IsResults, SearchResultsCount, SearchResult and SearchResultW to query that list (see code example further down). Once the result list is no longer needed it needs to be disposed of with a call to the ReleaseObject function from the CVCImg.dll.

Returns

TRUE if the search was successful, FALSE otherwise. Typical reasons for failure are:

• handle does not point to a valid Minos classifier
• image does not refer to a valid Common Vision Blox image
• index was not from the range [0...ImageDimension(image)-1] -maxSearch` was less than 1

See also

ReadTokenW, ReadToken, ReadCharacterList, ReadTokenFirst, SearchFirst, SearchFirstW, Testing OCR Classifiers

ReleaseClf()

cvbbool_t ReleaseClf

(

CLF &

handle

)

This function releases (decreases the reference counter) of a CLF object.

Decrementing the reference count of a classifier once it is no longer needed or shared ownership ended is essential to prevent memory leaks. Always call ReleaseClf on objects that your code has created or you have called ShareClf on once they are no longer needed or shared.

Parameters

[in]

handle

Handle to the Minos classifier to be released. If the reference classifier ceases to exist after the ReleaseClf call, the parameter handle will be overwritten with a nullptr, otherwise it will not be touched.

Returns

TRUE if the call to ReleaseClf reduced the reference count to zero and the object has been destroyed, FALSE otherwise.

ReleaseResults()

cvbbool_t ReleaseResults

(

RESULTS &

handle

)

This function releases (decreases the reference counter) of a RESULTS object.

Decrementing the reference count of a result list once it is no longer needed or shared ownership ended is essential to prevent memory leaks. Always call ReleaseResults on objects that your code has created or you have called ShareResults on once they are no longer needed or shared.

Parameters

[in]

handle

Handle to the Minos classifier to be released. If the reference classifier ceases to exist after the ReleaseResults call, the parameter handle will be overwritten with a nullptr, otherwise it will not be touched.

Returns

TRUE if the call to ReleaseResults reduced the reference count to zero and the object has been destroyed, FALSE otherwise.

SearchAll()

cvbbool_t SearchAll	(	CLF	clf,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		cvbdim_t	radius,
		cvbval_t	maxSearch,
		RESULTS &	results
	)

Scans the search area for all occurrences of patterns of models trained in the Minos classifier clf.

The found patterns will be returned in a result list of type RESULTS which can then be processed using the functions IsResults, SearchResultsCount, SearchResult and SearchResultW.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	clf	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[in]	radius	Defines the locality of the local maxima that will be reported in the results parameter. Of any two results in that list that lie closer together than the value of radiusspecifies (in pixels) the result with the lower quality value will be discarded.
[in]	maxSearch	Maximum number of results to be reported in the resultslist.
[out]	results	List of result patterns that has been found. Use the functions IsResults, SearchResultsCount, SearchResult and SearchResultW to query that list (see code example further down). Once the result list is no longer needed it needs to be disposed of with a call to the ReleaseObject function from the CVCImg.dll.

Returns

TRUE if the call was successful, FALSE otherwise. If the return value is FALSE the results parameter will not be modified. Possible reasons for failure are:

• clf does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.
• radius parameter is less than zero
• maxSearch parameter is less than 1

See also

Multithreading in Minos, SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

Example Evaluate the list of results returned by SearchAll

// assumptions:
// - clf refers to a valid Minos classifier
// - img refers to a valid image that contains zero or more instances
//       of the object trained into the classifier clf
RESULTS results = nullptr;
TArea aoi;
MaxImageArea(img, aoi); // scan entire image
if (SearchAll(clf, img, 0, 1000, aoi, 6, 1000, results) && IsResults(results))
{
  auto numResults = SearchResultsCount(results);
  for (int i = 0; i < numResults; ++i)
  {
    double xPos, yPos, quality, dx, dy;
    xPos = yPos = quality = dx = dy = 0.0;
    long id = 0;
    char* classname = nullptr;
    SearchResult(results, i,
      quality, xPos, yPos, dx, dy, classname, id);
    std::cout << "result #" << i << ": x = " << xPos << ", y = " << yPos;
    std::cout << ", q = " << quality << ", class: " << classname << std::endl;
  }
  ReleaseObject(results);
}
else
  std::cout << "SearchAll() call failed." << std::endl;

SearchFirst()

cvbbool_t SearchFirst	(	CLF	clf,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		char *&	pstrName
	)

Scans the search area for the first pattern that corresponds to one of the models trained in the Minos classifier clf.

This search function will interrupt the search upon encountering the first instance of a pattern that has been trained in the Minos classifier referenced by clf which has greater than zero result quality.

Only the location, model properties and result quality of that first
result will be returned.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Parameters

[in]	clf	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]	quality	Receives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]	xPos	X position of the result pattern.
[out]	yPos	Y position of the result pattern.
[out]	dX	X component of the advance vector of the result.
[out]	dY	Y component of the advance vector of the result.
[out]	pstrName	Receives a pointer to the class ID of the result. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

Returns

TRUE if the call was successful, FALSE otherwise. Note that a call to SearchOptimum may have been successful but still did not yield a result. To determine whether or not a result has been found check if the value returned in quality is greater than zero. Possible reasons for failure are:

• clf does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.

See also

Multithreading in Minos, SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

SearchFirstW()

cvbbool_t SearchFirstW	(	CLF	clf,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		wchar_t *&	pstrName
	)

Scans the search area for the first pattern that corresponds to one of the models trained in the Minos classifier clf.

This search function will interrupt the search upon encountering the first instance of a pattern that has been trained in the Minos classifier referenced by clf which has greater than zero result quality.

Only the location, model properties and result quality of that first
result will be returned.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The functions CLFToMemory and MemoryToCLF may be used for creating clones of any Minos classifier.

Since

Common Vision Blox 13.00.000

Parameters

[in]	clf	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]	quality	Receives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]	xPos	X position of the result pattern.
[out]	yPos	Y position of the result pattern.
[out]	dX	X component of the advance vector of the result.
[out]	dY	Y component of the advance vector of the result.
[out]	pstrName	Receives a pointer to the class ID of the result. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

Returns

TRUE if the call was successful, FALSE otherwise. Note that a call to SearchOptimum may have been successful but still did not yield a result. To determine whether or not a result has been found check if the value returned in quality is greater than zero. Possible reasons for failure are:

• clf does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.

See also

Multithreading in Minos, SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

SearchOptimum()

cvbbool_t SearchOptimum	(	CLF	clf,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		char *&	pstrName
	)

Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf.

Only the location, model properties and result quality of the global maximum will be returned. 'Global' in this context refers to the area of interest and the maximum over all models that have been trained in the classifier clf.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The function DuplicateCLF may be used to create clones of any Minos classifier.

Parameters

[in]	clf	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]	quality	Receives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]	xPos	X position of the result pattern.
[out]	yPos	Y position of the result pattern.
[out]	dX	X component of the advance vector of the result.
[out]	dY	Y component of the advance vector of the result.
[out]	pstrName	Receives a pointer to the class ID of the result. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

Returns

TRUE if the call was successful, FALSE otherwise. Note that a call to SearchOptimum may have been successful but still did not yield a result. To determine whether or not a result has been found check if the value returned in quality is greater than zero. Possible reasons for failure are:

• clf does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.

See also

Multithreading in Minos, SearchAll, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

SearchOptimumW()

cvbbool_t SearchOptimumW	(	CLF	handle,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		wchar_t *&	pstrName
	)

Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf.

Only the location, model properties and result quality of the global maximum will be returned. 'Global' in this context refers to the area of interest and the maximum over all models that have been trained in the classifier clf.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The function DuplicateCLF may be used to create clones of any Minos classifier.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]	quality	Receives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]	xPos	X position of the result pattern.
[out]	yPos	Y position of the result pattern.
[out]	dX	X component of the advance vector of the result.
[out]	dY	Y component of the advance vector of the result.
[out]	pstrName	Receives a pointer to the class ID of the result. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

Returns

TRUE if the call was successful, FALSE otherwise. Note that a call to SearchOptimumW may have been successful but still did not yield a result. To determine whether or not a result has been found check if the value returned in quality is greater than zero. Possible reasons for failure are:

• clf does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.

See also

Multithreading in Minos, SearchAll, SearchOptimum, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

SearchResult()

cvbbool_t SearchResult	(	RESULTS	handle,
		cvbdim_t	index,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		char *&	pstrName,
		cvbval_t &	searchID
	)

This function reads an entry from a list of search results.

The list of results must be of type RESULTS. The functions that are capable of creating such lists are SearchAll, ReadCharacterList and SearchAll.

For examples on how to use this function please refer to the documentation of SearchAll, ReadCharacterList and OptCorrelations.

Parameters

[in]	handle	Handle to the result list.
[in]	index	Ordinal number of the list entry to be read. The index is (as usual) zero based, ranging from 0 to SearchResultsCount - 1.
[out]	quality	Pattern quality of the queried entry.
[out]	xPos	X position of the queried pattern.
[out]	yPos	Y position of the queried pattern.
[out]	dX	X component of the advance vector of the model corresponding to the referenced list entry.
[out]	dY	Y component of the advance vector of the model corresponding to the referenced list entry.
[out]	pstrName	Receives a pointer to the class ID of the result. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	searchID	This result property is relevant only in the context of the MTS-consistency check functions in which case it is the Index of the MTS-image containing a potentially forgotten positive instance.

Returns

TRUE if the list entry was queried successfully, FALSE otherwise. Possible reasons for failure are:

• handle does not refer to a valid Minos result list.
• index is less than zero or greater or equal SearchResultsCount

SearchResultsCount()

cvbval_t SearchResultsCount

(

RESULTS

handle

)

Returns the number of entries in a RESULTS list.

This function returns the number of entries in a list of search results as created by the functions SearchAll, ReadCharacterList, and OptCorrelations. See the documentations of either of these functions for a code example.

Parameters

[in]

handle

Handle to the result list to be queried.

Returns

Number of entries in a list of search results or -1 if handle does not refer to a valid Minos result list.

SearchResultW()

cvbbool_t SearchResultW	(	RESULTS	handle,
		cvbdim_t	index,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		wchar_t *&	pstrName,
		cvbval_t &	searchID
	)

This function reads an entry from a list of search results.

The list of results must be of type RESULTS. The functions that are capable of creating such lists are SearchAll, ReadCharacterList and SearchAll.

For examples on how to use this function please refer to the documentation of SearchAll, ReadCharacterList and OptCorrelations.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the result list.
[in]	index	Ordinal number of the list entry to be read. The index is (as usual) zero based, ranging from 0 to SearchResultsCount - 1.
[out]	quality	Pattern quality of the queried entry.
[out]	xPos	X position of the queried pattern.
[out]	yPos	Y position of the queried pattern.
[out]	dX	X component of the advance vector of the model corresponding to the referenced list entry.
[out]	dY	Y component of the advance vector of the model corresponding to the referenced list entry.
[out]	pstrName	Receives a pointer to the class ID of the result. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more
[out]	searchID	This result property is relevant only in the context of the MTS-consistency check functions in which case it is the Index of the MTS-image containing a potentially forgotten positive instance.

Returns

TRUE if the list entry was queried successfully, FALSE otherwise. Possible reasons for failure are:

• handle does not refer to a valid Minos result list.
• index is less than zero or greater or equal SearchResultsCount

SetCLFComment()

cvbbool_t SetCLFComment	(	CLF	handle,
		const char *	pstrComment
	)

Sets the comment string associated on a classifier.

The comment string is a read- and writable property of each Minos classifier and may be used for storing custom information inside the classifier.

Parameters

[in]	handle	Handle to the Minos classifier on which to set the comment string.
[in]	pstrComment	Pointer to a zero-terminated string containing the comment to be set on the classifier.

Returns

TRUE if the comment string has been set successfully, FALSE if handle does not refer to a valid Minos classifier.

See also

SetCLFCommentW, CLFComment

SetCLFCommentW()

cvbbool_t SetCLFCommentW	(	CLF	handle,
		const wchar_t *	pstrComment
	)

Sets the comment string associated on a classifier.

The comment string is a read- and writable property of each Minos classifier and may be used for storing custom information inside the classifier.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier on which to set the comment string.
[in]	pstrComment	Pointer to a zero-terminated string containing the comment to be set on the classifier.

Returns

TRUE if the comment string has been set successfully, FALSE if handle does not refer to a valid Minos classifier.

See also

SetCLFComment, CLFComment

SetCLFModelData()

cvbbool_t SetCLFModelData	(	CLF	handle,
		cvbval_t	index,
		const char *	pstrName,
		cvbdim_t	advanceX,
		cvbdim_t	advanceY
	)

This function sets model data in the given classifier.

The model for which information should be modified is referred to by an index ranging from zero to the number returned by NumCLFModels - 1.

Parameters

[in]	handle	Handle to the Minos classifier.
[in]	index	Index of the model for which to set the data. Must be in the range [0...NumCLFModels(handle) - 1].
[in]	pstrName	Model name to be set.
[in]	advanceX	X component of the advance vector.
[in]	advanceY	Y component of the advance vector.

Returns

TRUE if the model data were set successfully, FALSE otherwise. Typical error conditions are:

• handle does not refer to a valid Minos classifier.
• index is outside the range [0...NumCLFModels(handle)-1].

See also

GetCLFModelData, GetCLFModelDataW, SetCLFModelDataW

SetCLFModelDataW()

cvbbool_t SetCLFModelDataW	(	CLF	handle,
		cvbval_t	index,
		const wchar_t *	pstrName,
		cvbdim_t	advanceX,
		cvbdim_t	advanceY
	)

This function sets model data in the given classifier.

The model for which information should be modified is referred to by an index ranging from zero to the number returned by NumCLFModels - 1.

Parameters

[in]	handle	Handle to the Minos classifier.
[in]	index	Index of the model for which to set the data. Must be in the range [0...NumCLFModels(handle) - 1].
[in]	pstrName	Model name to be set.
[in]	advanceX	X component of the advance vector.
[in]	advanceY	Y component of the advance vector.

Returns

TRUE if the model data were set successfully, FALSE otherwise. Typical error conditions are:

• handle does not refer to a valid Minos classifier.
• index is outside the range [0...NumCLFModels(handle)-1].

See also

GetCLFModelData, GetCLFModelDataW, SetCLFModelData

SetCLFQualityType()

cvbbool_t SetCLFQualityType	(	CLF	handle,
		QualityMeasureMethod	method
	)

Sets the quality norm for pattern recognition with a classifier.

The quality of a Minos search result may be measured in one of two different ways:

• normalized (Quality_ReturnCorrelation) by calculating the correlation between the pixels available at the result location versus those from the trained features
• unnormalized (Quality_Unnormalized) by calculating the average contrast encountered during a search operation

Both approaches have their place: Unnormalized is slightly (but only slightly) faster than normalized, but normalized provides quality values that are globally comparable. Choose whatever suits your requirements best.

Note that when changing the quality measure it usually makes sense to update the quality threshold accordingly (SetCLFThreshold) because the different quality measures are working with different value ranges.

Parameters

[in]	handle	Handle to the Minos classifier on which to set the quality measure method.
[in]	method	Quality measure to use for subsequent search operations.

Returns

TRUE if the method has been set successfully, FALSE otherwise (in this case handle does either not refer to a valid Minos classifier or method is not one of the enum values defined in QualityMeasureMethod).

See also

QualityMeasureMethod, GetCLFQualityType, SetCLFThreshold

SetCLFThreshold()

cvbbool_t SetCLFThreshold	(	CLF	handle,
		double	threshold
	)

Sets the quality threshold for pattern recognition on a classifier.

The Threshold specifies the minimum quality that a result must achieve before being reported by any of the search functions that a Minos classifier might be used with. Note that the threshold is measured in terms of the classifier's currently selected quality type (see SetCLFQualityType/GetCLFQualityType) - choose the threshold value accordingly.

• If Quality_Unnormalized has been set, the threshold should be chosen in the range [0...255]
• If Quality_ReturnCorrelation has been set, threshold should be from the range [0...1].

Parameters

[in]	handle	Handle to the Minos classifier on which to set the threshold.
[in]	threshold	Quality threshold to be set.

Returns

TRUE if the threshold has been set successfully, FALSE otherwise. Typical error conditions are:

• handle does not refer to a valid Minos classifier
• threshold is less than zero

See also

GetCLFThreshold, GetCLFQualityType, SetCLFQualityType

SetCLFTrigger()

cvbbool_t SetCLFTrigger	(	CLF	handle,
		cvbval_t	trigger
	)

Sets the minimum required contrast for pattern recognition with the classifier.

The trigger specifies the minimum contrast amplitude required for the feature verification of Minos to respond. The default value is the one that has been used when generating the classifier (specified in the TLearnControlStructure, recommended is a value of 8 here).

Note that in most cases it is adequate to simply use the value set at classifier generation. Only if the images you plan to use the classifier on have a significantly lower contrast than the content of the training set lowering the trigger value may increase the quality of the search results.

Parameters

[in]	handle	Handle to the Minos classifier for which to change the contrast trigger value.
[in]	trigger	New trigger value to be set. Acceptable values are within the range [1...255], but useful values are typically around 8.

Returns

TRUE if the contrast trigger was changed successfully, FALSE otherwise. Typical error conditions are

• handle does not refer to a valid Minos classifier
• trigger is less than 1

See also

GetCLFTrigger, TLearnControlStructure

ShareClf()

cvbbool_t ShareClf

(

CLF

handle

)

Increments the reference count for a CLF object.

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. Each call to ShareClf must be countered with a call to ReleaseClf once the shared ownership ends (e.g. because the thread has terminated or the form has been destroyed) to prevent memory leaks.

Parameters

[in]

handle

Handle to the Minos classifier to be shared.

Returns

TRUE if the reference count of handle was incremented successfully, FALSE otherwise.

ShareResults()

cvbbool_t ShareResults

(

RESULTS

handle

)

Increments the reference count for a RESULTS object.

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. Each call to ShareResults must be countered with a call to ReleaseResults once the shared ownership ends (e.g. because the thread has terminated or the form has been destroyed) to prevent memory leaks.

Parameters

[in]

handle

Handle to the Minos result list to be shared.

Returns

TRUE if the reference count of handle was incremented successfully, FALSE otherwise.

SortResultsByName()

cvbbool_t SortResultsByName

(

RESULTS

handle

)

Sorts a list of search results, as created by the functions SearchAll or ReadCharacterList alphabetically by class ID.

Of course sorting the list will reorder the result indices, so any indices retrieved prior to sorting will be invalidated by the sort operation.

By the way: Technically the function OptCorrelations also generates a result list of type RESULTS, but the class IDs in that list are all identical (?).

Parameters

[in]

handle

Handle to the result list to be sorted.

Returns

TRUE if the sort operation succeeded, FALSE if handle does not refer to a valid Minos result list.

See also

SortResultsByQuality, SortResultsByPosition

SortResultsByPosition()

cvbbool_t SortResultsByPosition	(	RESULTS	handle,
		double	projectionX,
		double	projectionY
	)

Sorts a list of search results, as created by the functions SearchAll, ReadCharacterList or OptCorrelations along a definable vector.

For this function the sort criterion is the inner product of the result and the projection vector defined by projectionX and projectionY. Thereby it is possible to sort results according to their position along a definable direction. For example with projectionX = 1 and projectionY = 0 the results will be sorted by increasing x position (while the y position is ignored).

Of course sorting the list will reorder the result indices, so any indices retrieved prior to sorting will be invalidated by the sort operation.

Parameters

[in]	handle	Handle to the result list to be sorted.
[in]	projectionX	X component of the vector specifying the sorting direction.
[in]	projectionY	Y component of the vector specifying the sorting direction.

Returns

TRUE if the sort operation succeeded, FALSE if handle does not refer to a valid Minos result list.

See also

SortResultsByName, SortResultsByQuality

SortResultsByQuality()

cvbbool_t SortResultsByQuality

(

RESULTS

handle

)

Sorts a list of search results, as created by the functions SearchAll, ReadCharacterList or OptCorrelations by decreasing order of quality.

Of course sorting the list will reorder the result indices, so any indices retrieved prior to sorting will be invalidated by the sort operation.

Parameters

[in]

handle

Handle to the result list to be sorted.

Returns

TRUE if the sort operation succeeded, FALSE if handle does not refer to a valid Minos result list.

See also

SortResultsByName, SortResultsByPosition

SubpixelOptimum()

cvbbool_t SubpixelOptimum	(	CLF	handle,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		char *&	pstrName
	)

Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf and returns its position with sub pixel accuracy.

Only the location, model properties and result quality of the global maximum will be returned. 'Global' in this context refers to the area of interest and the maximum over all models that have been trained in the classifier clf.

If the density was less than 1000 this location information will subsequently refined to pixel accuracy as if scanned at a density of 1000, before a parabolic fit to the quality surface in the neighborhood of the maximum is used for estimating a sub pixel accurate position of the pattern.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The function DuplicateCLF may be used to create clones of any Minos classifier.

This function may not be used with classifiers that have been created with a 16 bit version of Minos (see IsOldCLF).

Parameters

[in]	handle	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]	quality	Receives the quality of the result. When zero, none of the objects in the classifier handle has been found in the image img.
[out]	xPos	X position of the result pattern.
[out]	yPos	Y position of the result pattern.
[out]	dX	X component of the advance vector of the result.
[out]	dY	Y component of the advance vector of the result.
[out]	pstrName	Receives a pointer to the class ID of the result. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

Returns

TRUE if the call was successful, FALSE otherwise. Note that a call to SubpixelOptimum may have been successful but still did not yield a result. To determine whether or not a result has been found check if the value returned in quality is greater than zero. Possible reasons for failure are:

• handle does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.

See also

Multithreading in Minos, SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

SubpixelOptimumW()

cvbbool_t SubpixelOptimumW	(	CLF	handle,
		IMG	img,
		cvbdim_t	index,
		cvbdensity_t	density,
		TArea	area,
		double &	quality,
		double &	xPos,
		double &	yPos,
		double &	dX,
		double &	dY,
		wchar_t *&	pstrName
	)

Scans the search area for the pattern that corresponds best to one of the models trained in the Minos classifier clf and returns its position with sub pixel accuracy.

Only the location, model properties and result quality of the global maximum will be returned. 'Global' in this context refers to the area of interest and the maximum over all models that have been trained in the classifier clf.

If the density was less than 1000 this location information will subsequently refined to pixel accuracy as if scanned at a density of 1000, before a parabolic fit to the quality surface in the neighborhood of the maximum is used for estimating a sub pixel accurate position of the pattern.

Attention

When using one of the search functions of Minos (SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SubpixelOptimumW, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList) in multiple threads simultaneously you must make sure that each thread is using its own copy of the classifier! Violating this rule will produce undefined behavior, potentially including (but not limited to) access violations. The function DuplicateCLF may be used to create clones of any Minos classifier.

This function may not be used with classifiers that have been created with a 16 bit version of Minos (see IsOldCLF).

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier.
[in]	img	Handle to the image to be processed.
[in]	index	Plane of the image img to be processed.
[in]	density	Scan density to apply when searching for the best match. Must be in the range [0...1000] with 1000 implying that every single pixel of the area of interest will be scanned whereas e.g. 500 means that only every other pixel in x and y direction will be scanned (greatly decreasing processing time but also potentially deteriorating the search results).
[in]	area	Area in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]	quality	Receives the quality of the result. When zero, none of the objects in the classifier handle has been found in the image img.
[out]	xPos	X position of the result pattern.
[out]	yPos	Y position of the result pattern.
[out]	dX	X component of the advance vector of the result.
[out]	dY	Y component of the advance vector of the result.
[out]	pstrName	Receives a pointer to the class ID of the result. Note that if the class ID contains characters that are not printable with the process's current code page, these characters will be returned as ?. The returned pointer is a pointer to an internal string in the classifier which means: you must not call free() (or similar functions) on this pointer; the string will be disposed of by the classifier eventually and it is not the caller's responsibility to take care of this the pointer must not be used to write to that string; only read access is acceptable once the classifier has been disposed of this pointer will no longer be valid and must not be dereferenced any more

Returns

TRUE if the call was successful, FALSE otherwise. Note that a call to SubpixelOptimumW may have been successful but still did not yield a result. To determine whether or not a result has been found check if the value returned in quality is greater than zero. Possible reasons for failure are:

• handle does not refer to a valid Minos classifier.
• img does not refer to a valid Common Vision Blox image.

See also

Multithreading in Minos, SearchAll, SearchOptimum, SearchOptimumW, SubpixelOptimum, SearchFirst, SearchFirstW, ReadToken, ReadTokenW, ReadTokenFirst, ReadTokenFirstW, ReadCharacterList

TruncateResults()

cvbbool_t TruncateResults	(	RESULTS	handle,
		cvbval_t	numEntries
	)

Truncate a list of search results.

This function simply reduces a result list as created by the functions SearchAll, ReadCharacterList or OptCorrelations to the first numEntries entries.

Parameters

[in]	handle	Handle to the result list.
[in]	numEntries	Number of entries to retain. If the list contains fewer or equal to numEntries entries, it is left unchanged.

Returns

TRUE if the sort operation succeeded, FALSE if handle does not refer to a valid Minos result list.

WriteCLFFile()

cvbbool_t WriteCLFFile	(	CLF	handle,
		const char *	pstrFileName
	)

Stores a Minos classifier in a file.

Note that since Common Vision Blox 13.00.000 WriteCLFFile will save the strings in the classifier passed to it (model names, comment) using UTF8 encoding and prepended with a BOM. Loading such a classifier with older builds of Common Vision Blox will work, but the BOM (a sequence of three non-regular characters) will be visible:

To prevent this, use WriteCLFFileEx - with that function the character encoding for the strings in the serialized classifiers is selectable.

Parameters

[in]	handle	Handle to the Minos classifier to be stored.
[in]	pstrFileName	Name of file to which to save the Minos classifier.

Returns

TRUE (non-zero value) on success, FALSE otherwise.

See also

LoadCLFFile, LoadCLFFileW, WriteCLFFileW, WriteCLFFileEx, WriteCLFFileExW

WriteCLFFileEx()

cvbbool_t WriteCLFFileEx	(	CLF	handle,
		const char *	pstrFileName,
		TMinosCharacterEncoding	encoding
	)

Stores a Minos classifier with selectable string encoding in a file.

Starting with Common Vision Blox 13.00.000 Minos is fully Unicode capable, meaning that all strings (model names, comments) may be given using the UTF16 character set and files may be stored using Unicode file names.

Internally Unicode strings will be stored using UTF8 encoding with a BOM prepended to indicate the (potential) use of Unicode characters. This may generate friction with previous versions of Common Vision Blox (see the description of WriteCLFFile), so for backward compatibility is is sometimes desirable to store the strings using simple ASCII encoding rather than UTF8 - which is exactly what this function permits.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier to be stored.
[in]	pstrFileName	Name of file to which to save the Minos classifier.
[in]	encoding	Character encoding to be used for the strings in the classifier (model names and comment). See TMinosCharacterEncoding for a list of possible values.

Returns

TRUE (non-zero value) on success, FALSE otherwise.

See also

LoadCLFFile, LoadCLFFileW, WriteCLFFile, WriteCLFFileW, WriteCLFFileExW

WriteCLFFileExW()

cvbbool_t WriteCLFFileExW	(	CLF	handle,
		const wchar_t *	pstrFileName,
		TMinosCharacterEncoding	encoding
	)

Stores a Minos classifier with selectable string encoding in a file.

Starting with Common Vision Blox 13.00.000 Minos is fully Unicode capable, meaning that all strings (model names, comments) may be given using the UTF16 character set and files may be stored using Unicode file names.

Internally Unicode strings will be stored using UTF8 encoding with a BOM prepended to indicate the (potential) use of Unicode characters. This may generate friction with previous versions of Common Vision Blox (see the description of WriteCLFFile), so for backward compatibility is is sometimes desirable to store the strings using simple ASCII encoding rather than UTF8 - which is exactly what this function permits.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier to be stored.
[in]	pstrFileName	Name of file to which to save the Minos classifier.
[in]	encoding	Character encoding to be used for the strings in the classifier (model names and comment). See TMinosCharacterEncoding for a list of possible values.

Returns

TRUE (non-zero value) on success, FALSE otherwise.

See also

LoadCLFFile, LoadCLFFileW, WriteCLFFile, WriteCLFFileW, WriteCLFFileEx

WriteCLFFileW()

cvbbool_t WriteCLFFileW	(	CLF	handle,
		const wchar_t *	pstrFileName
	)

Stores a Minos classifier in a file.

Note that WriteCLFFileW will save the strings in the classifier passed to it (model names, comment) using UTF8 encoding and prepended with a BOM. Loading such a classifier with older builds of Common Vision Blox will work, but the BOM (a sequence of three non-regular characters) will be visible:

To prevent this, use WriteCLFFileExW - with that function the character encoding for the strings in the serialized classifiers is selectable.

Since

Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos classifier to be stored.
[in]	pstrFileName	Name of file to which to save the Minos classifier.

Returns

TRUE (non-zero value) on success, FALSE otherwise.

See also

LoadCLFFile, LoadCLFFileW, WriteCLFFile, WriteCLFFileEx, WriteCLFFileExW