Minos (MinosCVC.dll) 14.0
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]handleHandle 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]handleHandle 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]handleHandle 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]handleHandle 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]handleHandle 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]handleHandle 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]inputCLFHandle to the input Minos classifier for whose models the advance vectors are to be adjusted.
[in]dXX component of the new global advance vector.
[in]dYY component of the new global advance vector.
[out]outputCLFReceives 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]handleHandle to the Minos classifier to be serialized.
[in]memoryPoints to the beginning of the memory block to which the classifier should be serialized.
[in]capacitySize 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);
void * CLF
Handle to a Minos classifier.
Definition: iMinosCVC.h:52
cvbbool_t CLFToMemory(CLF handle, void *memory, size_t capacity)
Serialize a Minos classifier into a memory buffer.
Definition: MinosSearchExport.cpp:769
intptr_t GetCLFSize(CLF handle)
Query the memory consumption of a classifier.
Definition: MinosSearchExport.cpp:677
cvbbool_t MemoryToCLF(void *memory, cvbval_t capacity, CLF &clf)
Deserialize a classifier that was previously serialized with CLFToMemory.
Definition: MinosSearchExport.cpp:825

◆ 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]inputCLFHandle to the Minos classifier to be transformed.
[in]matrix2x2 transformation matrix to be applied.
[out]outputCLFReceives 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]inputMinos classifier to be cloned.
[out]outputWill 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]handleHandle to the Minos classifier.
[out]extentLeftLeft extent.
[out]extentTopTop extent.
[out]extentRightRight extent.
[out]extentBottomBottom 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]handleHandle to the Minos classifier to be queried.
[out]lcsReceives 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]handleHandle to the Minos classifier for which to query model data.
[in]indexIndex of the model for which to query the data. Must be in the range [0...NumCLFModels(handle)-1].
[out]pstrNameReceives 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]advanceXX component of the advance vector.
[out]advanceYY 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]handleHandle to the Minos classifier for which to query model data.
[in]indexIndex of the model for which to query the data. Must be in the range [0...NumCLFModels(handle)-1].
[out]pstrNameReceives 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]advanceXX component of the advance vector.
[out]advanceYY 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]handleHandle to the Minos classifier to be queried.
[out]methodCurrently 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]handleHandle 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]handleHandle to the Minos classifier on which to query the threshold.
[out]thresholdCurrently 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]handleHandle to the Minos classifier for which to query the contrast trigger value.
[out]triggerCurrently 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]handleHandle 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]handleHandle 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]handleHandle 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]clfIf loading the classifier succeeded, this parameter will receive the handle to the Minos classifier.
[in]pstrFileNameName 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]clfIf loading the classifier succeeded, this parameter will receive the handle to the Minos classifier.
[in]pstrFileNameName 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]memoryMemory buffer containing the serialized classifier.
[in]capacitySize of the serialized classifier.
[out]clfWill 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]handleHandle 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]handleHandle of the Minos classifier to be used.
[in]imageHandle of the image to use the classifier on.
[in]indexIndex of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]densityScan 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]areaArea 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]translatedAreaExpectation 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]maxSearchMaximal number of results to gather. Defines the upper limit for the size of the list returned in results;
[out]resultsList 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]handleHandle of the Minos classifier to be used.
[in]imageHandle of the image to use the classifier on.
[in]indexIndex of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]densityScan 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]areaArea 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]translatedAreaExpectation 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]maxSearchMaximal 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]qualityPattern quality of the last pattern encountered; if no pattern was found, quality will be set to zero.
[out]xPosX position of the last pattern found. If no pattern was found, xPos will not be modified.
[out]yPosY position of the last pattern found. If no pattern was found, yPos will not be modified.
[out]dXX component of the advance vector of the last pattern found. If no pattern was found, dX will not be modified.
[out]dYY component of the advance vector of the last pattern found. If no pattern was found, dY will not be modified.
[out]pstrNameReceives 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]charCountNumber of characters that have been written to the buffer pointed to by pstrName.
[in]pstrTokenPointer 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;
}
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 Mino...
Definition: MinosSearchExport.cpp:2109
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.
Definition: MinosSearchExport.cpp:2812

◆ 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]handleHandle of the Minos classifier to be used.
[in]imageHandle of the image to use the classifier on.
[in]indexIndex of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]densityScan 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]areaArea 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]translatedAreaExpectation 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]maxSearchMaximal 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]qualityPattern quality of the first pattern encountered; if no pattern was found, quality will be set to zero.
[out]xPosX position of the first pattern found. If no pattern was found, xPos will not be modified.
[out]yPosY position of the first pattern found. If no pattern was found, yPos will not be modified.
[out]dXX component of the advance vector of the first pattern found. If no pattern was found, dX will not be modified.
[out]dYY component of the advance vector of the first pattern found. If no pattern was found, dY will not be modified.
[out]pstrNameReceives 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]charCountNumber of characters that have been written to the buffer pointed to by pstrName.
[in]pstrTokenPointer 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]handleHandle of the Minos classifier to be used.
[in]imageHandle of the image to use the classifier on.
[in]indexIndex of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]densityScan 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]areaArea 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]translatedAreaExpectation 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]maxSearchMaximal 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]qualityPattern quality of the first pattern encountered; if no pattern was found, quality will be set to zero.
[out]xPosX position of the first pattern found. If no pattern was found, xPos will not be modified.
[out]yPosY position of the first pattern found. If no pattern was found, yPos will not be modified.
[out]dXX component of the advance vector of the first pattern found. If no pattern was found, dX will not be modified.
[out]dYY component of the advance vector of the first pattern found. If no pattern was found, dY will not be modified.
[out]pstrNameReceives 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]charCountNumber of characters that have been written to the buffer pointed to by pstrName.
[in]pstrTokenPointer 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]handleHandle of the Minos classifier to be used.
[in]imageHandle of the image to use the classifier on.
[in]indexIndex of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]densityScan 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]areaArea 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]translatedAreaExpectation 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]maxSearchMaximal 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]qualityPattern quality of the last pattern encountered; if no pattern was found, quality will be set to zero.
[out]xPosX position of the last pattern found. If no pattern was found, xPos will not be modified.
[out]yPosY position of the last pattern found. If no pattern was found, yPos will not be modified.
[out]dXX component of the advance vector of the last pattern found. If no pattern was found, dX will not be modified.
[out]dYY component of the advance vector of the last pattern found. If no pattern was found, dY will not be modified.
[out]pstrNameReceives 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]charCountNumber of characters that have been written to the buffer pointed to by pstrName.
[in]pstrTokenPointer 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;
}
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 Mino...
Definition: MinosSearchExport.cpp:2196
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.
Definition: MinosSearchExport.cpp:3057

◆ 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]handleHandle of the Minos classifier to be used.
[in]imageHandle of the image to use the classifier on.
[in]indexIndex of the plane in the image to use the classifier on. Valid values for index are in the range [0...ImageDimension(image)[.
[in]densityScan 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]areaArea 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]translatedAreaExpectation 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]maxSearchMaximal number of results to gather. Defines the upper limit for the size of the list returned in results;
[out]resultsList 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]handleHandle 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]handleHandle 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]clfHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[in]radiusDefines 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]maxSearchMaximum number of results to be reported in the resultslist.
[out]resultsList 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;
void * RESULTS
Handle to a list of Minos search results.
Definition: iMinosCVC.h:65
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.
Definition: MinosSearchExport.cpp:2495
cvbbool_t IsResults(RESULTS handle)
Verifies whether a handle refers to a valid Minos result list.
Definition: MinosSearchExport.cpp:91
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.
Definition: MinosSearchExport.cpp:165
cvbval_t SearchResultsCount(RESULTS handle)
Returns the number of entries in a RESULTS list.
Definition: MinosSearchExport.cpp:110

◆ 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]clfHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]qualityReceives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]xPosX position of the result pattern.
[out]yPosY position of the result pattern.
[out]dXX component of the advance vector of the result.
[out]dYY component of the advance vector of the result.
[out]pstrNameReceives 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]clfHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]qualityReceives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]xPosX position of the result pattern.
[out]yPosY position of the result pattern.
[out]dXX component of the advance vector of the result.
[out]dYY component of the advance vector of the result.
[out]pstrNameReceives 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]clfHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]qualityReceives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]xPosX position of the result pattern.
[out]yPosY position of the result pattern.
[out]dXX component of the advance vector of the result.
[out]dYY component of the advance vector of the result.
[out]pstrNameReceives 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]handleHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]qualityReceives the quality of the result. When zero, none of the objects in the classifier clf has been found in the image img.
[out]xPosX position of the result pattern.
[out]yPosY position of the result pattern.
[out]dXX component of the advance vector of the result.
[out]dYY component of the advance vector of the result.
[out]pstrNameReceives 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]handleHandle to the result list.
[in]indexOrdinal number of the list entry to be read. The index is (as usual) zero based, ranging from 0 to SearchResultsCount - 1.
[out]qualityPattern quality of the queried entry.
[out]xPosX position of the queried pattern.
[out]yPosY position of the queried pattern.
[out]dXX component of the advance vector of the model corresponding to the referenced list entry.
[out]dYY component of the advance vector of the model corresponding to the referenced list entry.
[out]pstrNameReceives 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]searchIDThis 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]handleHandle 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]handleHandle to the result list.
[in]indexOrdinal number of the list entry to be read. The index is (as usual) zero based, ranging from 0 to SearchResultsCount - 1.
[out]qualityPattern quality of the queried entry.
[out]xPosX position of the queried pattern.
[out]yPosY position of the queried pattern.
[out]dXX component of the advance vector of the model corresponding to the referenced list entry.
[out]dYY component of the advance vector of the model corresponding to the referenced list entry.
[out]pstrNameReceives 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]searchIDThis 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]handleHandle to the Minos classifier on which to set the comment string.
[in]pstrCommentPointer 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]handleHandle to the Minos classifier on which to set the comment string.
[in]pstrCommentPointer 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]handleHandle to the Minos classifier.
[in]indexIndex of the model for which to set the data. Must be in the range [0...NumCLFModels(handle) - 1].
[in]pstrNameModel name to be set.
[in]advanceXX component of the advance vector.
[in]advanceYY 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]handleHandle to the Minos classifier.
[in]indexIndex of the model for which to set the data. Must be in the range [0...NumCLFModels(handle) - 1].
[in]pstrNameModel name to be set.
[in]advanceXX component of the advance vector.
[in]advanceYY 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]handleHandle to the Minos classifier on which to set the quality measure method.
[in]methodQuality 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.

Parameters
[in]handleHandle to the Minos classifier on which to set the threshold.
[in]thresholdQuality 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]handleHandle to the Minos classifier for which to change the contrast trigger value.
[in]triggerNew 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]handleHandle 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]handleHandle 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]handleHandle 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]handleHandle to the result list to be sorted.
[in]projectionXX component of the vector specifying the sorting direction.
[in]projectionYY 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]handleHandle 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]handleHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]qualityReceives the quality of the result. When zero, none of the objects in the classifier handle has been found in the image img.
[out]xPosX position of the result pattern.
[out]yPosY position of the result pattern.
[out]dXX component of the advance vector of the result.
[out]dYY component of the advance vector of the result.
[out]pstrNameReceives 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]handleHandle to the Minos classifier.
[in]imgHandle to the image to be processed.
[in]indexPlane of the image img to be processed.
[in]densityScan 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]areaArea in the image img to be scanned (use MaxImageArea to generate an area that encompasses the entire image if necessary).
[out]qualityReceives the quality of the result. When zero, none of the objects in the classifier handle has been found in the image img.
[out]xPosX position of the result pattern.
[out]yPosY position of the result pattern.
[out]dXX component of the advance vector of the result.
[out]dYY component of the advance vector of the result.
[out]pstrNameReceives 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]handleHandle to the result list.
[in]numEntriesNumber 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]handleHandle to the Minos classifier to be stored.
[in]pstrFileNameName 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]handleHandle to the Minos classifier to be stored.
[in]pstrFileNameName of file to which to save the Minos classifier.
[in]encodingCharacter 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]handleHandle to the Minos classifier to be stored.
[in]pstrFileNameName of file to which to save the Minos classifier.
[in]encodingCharacter 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]handleHandle to the Minos classifier to be stored.
[in]pstrFileNameName 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