Functions
IMG	CreateImageFromInstance (MTSINSTANCE handle)
	Creates an image representing the specified MTSINSTANCE. More...

MTS	CreateMTS (double expRadius, double corThresh)
	This function creates a new, empty training set (MTS). More...

cvbbool_t	GetFeatureWindow (MTSMODEL handle, TArea &featureWindow)
	Returns the feature window an MTSMODEL. More...

IMG	GetImageFromImage (MTSIMAGE handle)
	Returns the handle to the Common Vision Blox image inside an MTSIMAGE. More...

MTSIMAGE	GetImageFromInstance (MTSINSTANCE handle)
	Returns a handle to the MTSIMAGE containing the specified MTSINSTANCE. More...

IMG	GetImageFromModel (MTSMODEL handle)
	This function returns the handle to the image representing a specified pattern model. More...

cvbbool_t	GetModelAdvance (MTSMODEL handle, double &dX, double &dY)
	Returns the advance vector associated with a pattern model. More...

MTSMODEL	GetModelFromInstance (MTSINSTANCE handle)
	Returns a handle to the MTSMODEL to which the specified MTSINSTANCE belongs. More...

char *	GetModelName (MTSMODEL handle)
	Returns a pointer to the model name string. More...

const wchar_t *	GetModelNameW (MTSMODEL handle)
	Returns a pointer to the model name string. More...

cvbbool_t	GetMTSCorelParams (MTS handle, double &expRadius, double &corThresh)
	Returns the currently used correlation parameters of a Minos training set. More...

cvbbool_t	GetMTSExtent (MTS handle, cvbdim_t &extentLeft, cvbdim_t &extentTop, cvbdim_t &extentRight, cvbdim_t &extentBottom)
	This function returns the extent of the training set. More...

MTS	GetMTSFromImage (MTSIMAGE handle)
	Returns a handle to the training set that owns the specified training set image. More...

MTS	GetMTSFromInstance (MTSINSTANCE handle)
	Returns a handle to the training set that owns the specified training set instance. More...

MTS	GetMTSFromModel (MTSMODEL handle)
	Returns a handle to the training set that owns the specified training set model. More...

cvbbool_t	GetMTSGlobalAdvance (MTS handle, cvbbool_t &useGlobalVector, double &globalX, double &globalY)
	Queries the global advance vectors setting on a Minos training set. More...

cvbbool_t	GetMTSLastFeatureWnd (MTS handle, TArea &area)
	Returns the feature window of the last model created for the MTS. More...

cvbbool_t	GetMTSModified (MTS handle, cvbbool_t &isModified)
	Queries a training set's internal modification flag. More...

intptr_t	GetMTSSize (MTS handle)
	Query the memory consumption of a training set. More...

cvbval_t	InstanceIndex (MTSINSTANCE handle)
	Returns the index of an MTSINSTANCE. More...

double	InstanceX (MTSINSTANCE handle)
	Retrieves the x coordinate of the position of an MTSINSTANCE. More...

double	InstanceY (MTSINSTANCE handle)
	Retrieves the y coordinate of the position of an MTSINSTANCE. More...

cvbbool_t	IsMTS (MTS handle)
	Verifies whether a handle refers to a valid Minos training set. More...

cvbbool_t	IsMTSImage (MTSIMAGE handle)
	Verifies whether a handle refers to a valid Minos training set image. More...

cvbbool_t	IsMTSInstance (MTSINSTANCE handle)
	Verifies whether a handle refers to a valid Minos training set instance. More...

cvbbool_t	IsMTSModel (MTSMODEL handle)
	Verifies whether a handle refers to a valid Minos training set model. More...

cvbbool_t	LearnCLFFromMTS (MTS handle, const char *pstrMTSName, TLearnControlStructure lcs, CLF &clfHandle)
	Creates a Minos classifier from a Minos training set. More...

cvbbool_t	LearnCLFFromMTSW (MTS handle, const wchar_t *pstrMTSName, TLearnControlStructure lcs, CLF &clfHandle)
	Creates a Minos classifier from a Minos training set. More...

cvbbool_t	LoadMTSFile (const char *pstrFileName, MTS &mts)
	Loads a Minos training set from a file. More...

cvbbool_t	LoadMTSFileW (const wchar_t *pstrFileName, MTS &mts)
	Loads a Minos training set from a file. More...

cvbbool_t	MemoryToMTS (void *memory, size_t capacity, MTS &mts)
	Deserialize a classifier that was previously serialized with MTSToMemory. More...

char *	MTSComment (MTS handle)
	Returns a pointer to the training set's comment string. More...

const wchar_t *	MTSCommentW (MTS handle)
	Returns a pointer to the training set's comment string. More...

cvbbool_t	MTSConsistencyCheck (MTS handle, double threshold, cvbdensity_t density, TFCheckProgress progress, void *pPrivate, RESULTS &results)
	Performs a consistency check on the entire training set to find instances that might have been forgotten in the training process. More...

MTSIMAGE	MTSImage (MTS handle, cvbval_t index)
	Returns a handle of one of the MTSIMAGE objects in a training set. More...

cvbbool_t	MTSImageCheck (MTSIMAGE handle, double threshold, cvbdensity_t density, TFCheckProgress progress, void *pPrivate, RESULTS &results)
	Performs a consistency check on a training set image to find instances that might have been forgotten in the training process. More...

cvbval_t	MTSImageIndex (MTSIMAGE handle)
	Returns the index of an MTSIMAGE. More...

MTSINSTANCE	MTSImageInstance (MTSIMAGE handle, cvbval_t index)
	Returns a handle to an instance in a MTSIMAGE. More...

MTSINSTANCE	MTSInstance (MTS handle, cvbval_t index)
	Returns a handle of one of the MTSINSTANCE objects in a training set. More...

MTSMODEL	MTSModel (MTS handle, cvbval_t index)
	Returns a handle of one of the MTSMODEL objects in a training set. More...

cvbbool_t	MTSModelCheck (MTSMODEL handle, double threshold, cvbdensity_t density, TFCheckProgress progress, void *pPrivate, RESULTS &results)
	Performs a consistency check with a specific model on the entire training set to find instances that might have been forgotten in the training process. More...

cvbbool_t	MTSModelImageCheck (MTSMODEL modelHandle, MTSIMAGE imageHandle, double threshold, cvbdensity_t density, TFCheckProgress progress, void *pPrivate, RESULTS &results)
	Performs a consistency check with a specific model on a specific training set image to find instances that might have been forgotten in the training process. More...

cvbval_t	MTSModelIndex (MTSMODEL handle)
	Returns the index of an MTSMODEL. More...

MTSINSTANCE	MTSModelInstance (MTSMODEL handle, cvbval_t index)
	Returns a handle to an instance in a MTSMODEL. More...

cvbbool_t	MTSToMemory (MTS handle, void *memory, size_t capacity)
	Serialize a Minos training set into a memory buffer. More...

cvbbool_t	MTSTransform (MTS inputMts, TMatrix matrix, MTS &outputMts)
	Geometrically transform an entire Minos training set. More...

cvbbool_t	MTSVerifyToken (MTS handle, IMG image, cvbdim_t index, TArea area, TArea translatedArea, double corThresh, const char *pstrToken, double &minCor, cvbval_t &count)
	Verifies OCR using normalized gray scale correlation. More...

cvbbool_t	MTSVerifyTokenW (MTS handle, IMG image, cvbdim_t index, TArea area, TArea translatedArea, double corThresh, const wchar_t *pstrToken, double &minCor, cvbval_t &count)
	Verifies OCR using normalized gray scale correlation. More...

MTSIMAGE	NewMTSImage (MTS handle, IMG image)
	Creates a new MTSIMAGE and adds it to a Minos training set. More...

MTSIMAGE	NewMTSImageIndex (MTS handle, IMG image, cvbval_t index)
	Creates a new MTSIMAGE and adds it to a Minos training set. More...

cvbbool_t	NewMTSInstance (MTSIMAGE image, const char *pstrName, cvbbool_t askForce, double &xPos, double &yPos, MTSINSTANCE &instance)
	Create a new sample instance for a pattern class. More...

cvbbool_t	NewMTSInstanceW (MTSIMAGE image, const wchar_t *pstrName, cvbbool_t askForce, double &xPos, double &yPos, MTSINSTANCE &instance)
	Create a new sample instance for a pattern class. More...

MTSMODEL	NewMTSModel (MTSIMAGE handle, const char *pstrName, double xPos, double yPos, TArea area)
	Creates a new pattern model. More...

MTSMODEL	NewMTSModelW (MTSIMAGE handle, const wchar_t *pstrName, double xPos, double yPos, TArea area)
	Creates a new pattern model. More...

cvbval_t	NumMTSClasses (MTS handle)
	Returns the number of distinguishable classes in a training set. More...

cvbval_t	NumMTSImageInstances (MTSIMAGE handle)
	Returns the number of instances marked in a MTSIMAGE. More...

cvbval_t	NumMTSImages (MTS handle)
	Returns the number of MTSIMAGE objects in a training set. More...

cvbval_t	NumMTSInstances (MTS handle)
	Returns the number of MTSINSTANCE objects in a training set. More...

cvbval_t	NumMTSModelInstances (MTSMODEL handle)
	Returns the number of instances representing a given pattern model. More...

cvbval_t	NumMTSModels (MTS handle)
	Returns the number of MTSMODEL objects in a training set. More...

cvbbool_t	ReleaseMts (MTS &handle)
	This function releases (decreases the reference counter) of a MTS object. More...

cvbbool_t	RemoveMTSImage (MTSIMAGE handle)
	Removes an MTSIMAGE from a training set. More...

cvbbool_t	RemoveMTSInstance (MTSINSTANCE handle)
	Removes an MTSINSTANCE from a training set. More...

cvbbool_t	RemoveMTSModel (MTSMODEL handle)
	Removes an MTSMODEL from a training set. More...

cvbbool_t	SetFeatureWindow (MTSMODEL handle, TArea featureWindow)
	Changes the feature window an MTSMODEL. More...

cvbbool_t	SetModelAdvance (MTSMODEL handle, double dX, double dY)
	Returns the advance vector associated with a pattern model. More...

cvbbool_t	SetModelName (MTSMODEL handle, const char *pstrName)
	Changes the name of an MTSMODEL. More...

cvbbool_t	SetModelNameW (MTSMODEL handle, const wchar_t *pstrName)
	Changes the name of an MTSMODEL. More...

cvbbool_t	SetMTSComment (MTS handle, const char *pstrComment)
	Sets the comment string on a Minos training set. More...

cvbbool_t	SetMTSCommentW (MTS handle, const wchar_t *pstrComment)
	Sets the comment string on a Minos training set. More...

cvbbool_t	SetMTSCorelParams (MTS handle, double expRadius, double corThresh)
	Set the correlation parameters for Minos training. More...

cvbbool_t	SetMTSGlobalAdvance (MTS handle, cvbbool_t useGlobalVector, double globalX, double globalY)
	Set the global advance vectors for all the models in a training set. More...

cvbbool_t	SetMTSModified (MTS handle, cvbbool_t isModified)
	Sets a training set's internal modification flag. More...

cvbbool_t	ShareMts (MTS handle)
	Increments the reference count for a MTS object. More...

cvbbool_t	TransformMTSImage (MTSIMAGE handle, TMatrix matrix)
	Geometrically transforms an MTSIMAGE in the training set. More...

cvbbool_t	TranslateModelOrigin (MTSMODEL handle)
	Update the origin position (a.k.a. anchor point) of an MTSMODEL. More...

cvbbool_t	WriteMTSFile (MTS handle, const char *pstrFileName)
	Stores a Minos training set to a file. More...

cvbbool_t	WriteMTSFileEx (MTS handle, const char *pstrFileName, TMinosCharacterEncoding encoding)
	Saves a training set to a file with selectable character encoding. More...

cvbbool_t	WriteMTSFileExW (MTS handle, const wchar_t *pstrFileName, TMinosCharacterEncoding encoding)
	Saves a training set to a file with selectable character encoding. More...

cvbbool_t	WriteMTSFileW (MTS handle, const wchar_t *pstrFileName)
	Stores a Minos training set to a file. More...

Detailed Description

Function Documentation

◆ CreateImageFromInstance()

IMG CreateImageFromInstance ( MTSINSTANCE handle )

Creates an image representing the specified MTSINSTANCE.

The returned Common Vision Blox image object is effectively cut out of the MTSIMAGE's encapsulated image (GetImageFromImage) using its location (InstanceX, InstanceY) and feature window (GetModelFromInstance, GetFeatureWindow).

Remember to call ReleaseObject(CVCImg.dll) on the handle returned by CreateImageFromInstance once it is no longer needed. Failure to do so will result in a memory leak.

Parameters

[in] handle Handle to the MTSINSTANCE for which to create the image.

Returns: If successful, CreateImageFromInstance will return the handle of a Common Vision Blox image representing the instances referred to by handle. Remember to dispose of this image with ReleaseObject once it is no longer needed. If the call fails (most likely because handle does not refer to a valid MTSINSTANCE), a nullptr will be returned.

◆ CreateMTS()

MTS CreateMTS	(	double	expRadius,
		double	corThresh
	)

This function creates a new, empty training set (MTS).

Note that the two parameters that are relevant for training classifiers become mutable properties of the training set. They will be evaluated and applied every time a new instance is added to the training set with NewMTSInstance or when TransformMTSImage is used.

Remember to dispose of the training set by calling ReleaseObject from the CVCImg.dll on it once it is no longer needed.

Parameters

[in]	expRadius	Expectation window radius. The expectation window radius defines a square area of width `expRadius * 2 + 1` centered around the location at which an instance is to be extracted: When trying to extract a new instance at the extraction position with NewMTSInstance (or indirectly via TransformMTSImage), Minos will use the function OptCorrelation on the expectation window to check if there is an alternative extraction position with a higher resemblance to the model available and if so, automatically use that alternative position for training. If you do not want to use this snap-in feature, simply set the expectation window radius to zero.
[in]	corThresh	Correlation threshold. When adding new instances either through NewMTSInstance or indirectly via TransformMTSImage) Minos will calculate the correlation (OptCorrelation) between the new instance location (which may have been altered by the snap-in feature; see description of `expRadius`) and the model image (as retrieved via GetImageFromModel). If the correlation is below the correlation threshold, Minos will generate a new model with the same name for the new instance (NewMTSInstance will show a message box before that to let the user confirm that the creation of a new model is ok).

Returns: Handle to the new created Minos training set, nullptr if the process ran out of memory.

See also: MTS, Guidelines for training font classifiers

◆ GetFeatureWindow()

cvbbool_t GetFeatureWindow	(	MTSMODEL	handle,
		TArea &	featureWindow
	)

Returns the feature window an MTSMODEL.

The feature window is the smallest rectangle sufficient to recognize the pattern on the basis of its contents. It is an axis-parallel rectangle with integer coordinates containing the point (0,0), and the left and top coordinates are therefore usually less than or equal to zero.

Parameters

[in]	handle	Handle to the MTSMODEL for which to query the feature window.
[out]	featureWindow	Current feature window.

Returns: TRUE if the feature window was queried successfully, FALSE if handle does not refer to a valid MTSMODEL.

See also: SetFeatureWindow

◆ GetImageFromImage()

IMG GetImageFromImage ( MTSIMAGE handle )

Returns the handle to the Common Vision Blox image inside an MTSIMAGE.

An object referred to by an MTSIMAGE handle is not an image like the ones referred to by an IMG handle! The MTSIMAGE is a container that combines an IMG with a list of the instances that have been marked in the image and a reference to owning training set. To retrieve the IMG from an MTSIMAGE use the function GetImageFromImage.

In a MTS image don't care points may be set to exclude regions of the image from counter sample extraction. (The training set image is a Common Vision Blox image with bit-overlay capability i.e. setting bit 0 of a pixel will mark this pixel to be excluded from counter sample search).

Note that querying the image from an MTSIMAGE object does not modify the reference count of either object. After querying, ownership of the returned image handle still lies exclusively with the MTSIMAGE from which the handle was retrieved and it is not necessary to call ReleaseObject once the image handle is no longer required. It is, however, necessary to call ShareObject on the image handle if the image is supposed to exist longer than the MTSIMAGE from which it was retrieved.

Parameters

[in] handle Handle to the MTSIMAGE from which to retrieve the image handle..

Returns: Handle to the image encapsulated by the MTSIMAGE object or nullptr if handle does not refer to a valid MTSIMAGE.

◆ GetImageFromInstance()

MTSIMAGE GetImageFromInstance ( MTSINSTANCE handle )

Returns a handle to the MTSIMAGE containing the specified MTSINSTANCE.

Note that querying the image from an MTSINSTANCE object does not modify the reference count of either object. After querying, ownership of the returned image handle still lies exclusively with the training set from which the handle was retrieved and it is not necessary to call ReleaseObject once the image handle is no longer required.

Attention: An object referred to by an MTSIMAGE handle is not an image like the ones referred to by an IMG handle! The MTSIMAGE is a container that combines an IMG with a list of the instances that have been marked in the image and a reference to owning training set. To retrieve the IMG from an MTSIMAGE use the function GetImageFromImage.

Parameters

[in] handle Handle to the MTSINSTANCE for which to query the MTSIMAGE.

Returns: Handle to the MTSIMAGE on which the instance referred to by handle is located if handle refers to a valid MTSINSTANCE; nullptr otherwise.

◆ GetImageFromModel()

IMG GetImageFromModel ( MTSMODEL handle )

This function returns the handle to the image representing a specified pattern model.

A pattern's model image is the average over all instances that have been added to the model. In the model image model-specific don't care points may be set to exclude regions of the model from feature extraction. (The model image is a Common Vision Blox image with bit-overlay capability i.e. setting bit 0 of a pixel will mark this pixel to be excluded).

Note that querying the image from an MTSMODEL object does not modify the reference count of either object. After querying, ownership of the returned image handle still lies exclusively with the MTSMODEL from which the handle was retrieved and it is not necessary to call ReleaseObject once the image handle is no longer required. It is, however, necessary to call ShareObject on the image handle if the image is supposed to exist longer than the MTSMODEL from which it was queried.

Parameters

[in] handle Handle to an MTSMODEL.

Returns: Handle to the model image or nullptr if handle does not refer to a valid MTSMODEL.

◆ GetModelAdvance()

cvbbool_t GetModelAdvance	(	MTSMODEL	handle,
		double &	dX,
		double &	dY
	)

Returns the advance vector associated with a pattern model.

The advance vector may be used by Minos to speed up reading of contiguous strings. See the documentation of ReadToken for a detailed description of how Minos uses the advance vector during read operations and a code sample.

Parameters

[in]	handle	Handle to an MTSMODEL
[out]	dX	X component of the advance vector.
[out]	dY	Y component of the advance vector.

Returns: TRUE if the advance vector was queried successfully, FALSE if handle does not refer to a valid MTSMODEL object.

See also: SetModelAdvance, SetMTSGlobalAdvance, GetMTSGlobalAdvance

◆ GetModelFromInstance()

MTSMODEL GetModelFromInstance ( MTSINSTANCE handle )

Returns a handle to the MTSMODEL to which the specified MTSINSTANCE belongs.

Note that querying the model from an MTSINSTANCE object does not modify the reference count of either object. After querying, ownership of the returned model handle still lies exclusively with the training set from which the handle was retrieved and it is not necessary to call ReleaseObject once the image handle is no longer required.

Parameters

[in] handle Handle to the MTSINSTANCE for which to query the MTSMODEL.

Returns: Handle to the MTSMODEL to which the instance referred to by handle has been added if handle refers to a valid MTSINSTANCE; nullptr otherwise.

◆ GetModelName()

char * GetModelName ( MTSMODEL handle )

Returns a pointer to the model name string.

Parameters

[in] handle Handle to an MTSMODEL.

Returns

Pointer to the model name if handle refers to a valid MTSMODEL, 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 training set 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: GetModelNameW, SetModelName, SetModelNameW

◆ GetModelNameW()

const wchar_t * GetModelNameW ( MTSMODEL handle )

Returns a pointer to the model name string.

Since: Common Vision Blox 13.00.000.

Parameters

[in] handle Handle to an MTSMODEL.

Returns

Pointer to the model name if handle refers to a valid MTSMODEL, nullptr otherwise.
The returned pointer is a pointer to an internal string in the training set 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: GetModelName, SetModelName, SetModelNameW

◆ GetMTSCorelParams()

cvbbool_t GetMTSCorelParams	(	MTS	handle,
		double &	expRadius,
		double &	corThresh
	)

Returns the currently used correlation parameters of a Minos training set.

The correlation parameters of a training set have either been defined when the training set has been created with CreateMTS or via a call to SetMTSCorelParams. They are mutable properties of the training set and will be evaluated and applied every time a new instance is added to the training set with NewMTSInstance or when TransformMTSImage is used.

Parameters

[in]	handle	Handle to the Minos training set.
[in]	expRadius	Expectation window radius. The expectation window radius defines a square area of width `expRadius * 2 + 1` centered around the location at which an instance is to be extracted: When trying to extract a new instance at the extraction position with NewMTSInstance (or indirectly via TransformMTSImage), Minos will use the function OptCorrelation on the expectation window to check if there is an alternative extraction position with a higher resemblance to the model available and if so, automatically use that alternative position for training. If you do not want to use this snap-in feature, simply set the expectation window radius to zero.
[in]	corThresh	Correlation threshold. When adding new instances either through NewMTSInstance or indirectly via TransformMTSImage) Minos will calculate the correlation (OptCorrelation) between the new instance location (which may have been altered by the snap-in feature; see description of `expRadius`) and the model image (as retrieved via GetImageFromModel). If the correlation is below the correlation threshold, Minos will generate a new model with the same name for the new instance (NewMTSInstance will show a message box before that to let the user confirm that the creation of a new model is ok).

Returns: TRUE if the correlation parameters have been queried successfully, FALSE if handle does not refer to a valid Minos training set.

See also: SetMTSCorelParams, CreateMTS

◆ GetMTSExtent()

cvbbool_t GetMTSExtent	(	MTS	handle,
		cvbdim_t &	extentLeft,
		cvbdim_t &	extentTop,
		cvbdim_t &	extentRight,
		cvbdim_t &	extentBottom
	)

This function returns the extent of the training set.

The extent of a Minos training set is defined as the smallest rectangle containing the feature windows of all models inside a training set positioned at the origin (0, 0). Therefore, the left and top extent of a training set are in most cases negative values.

Parameters

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

Returns: TRUE if the extent was queried successfully, FALSE if handle does not refer to a valid Minos training set.

◆ GetMTSFromImage()

MTS GetMTSFromImage ( MTSIMAGE handle )

Returns a handle to the training set that owns the specified training set image.

Note that calling this function will not modify the reference count of the training set object returned by this function.

Parameters

[in] handle Handle to the MTSIMAGE for which to query the owning training set.

Returns: Handle to the Minos training set that owns the MTSIMAGE referenced by handle. nullptr if handle does not reference a valid MTSIMAGE.

◆ GetMTSFromInstance()

MTS GetMTSFromInstance ( MTSINSTANCE handle )

Returns a handle to the training set that owns the specified training set instance.

Note that calling this function will not modify the reference count of the instance object returned by this function.

Parameters

[in] handle Handle to the MTSINSTANCE for which to query the owning training set.

Returns: Handle to the Minos training set that owns the MTSINSTANCE referenced by handle. nullptr if handle does not reference a valid MTSINSTANCE.

◆ GetMTSFromModel()

MTS GetMTSFromModel ( MTSMODEL handle )

Returns a handle to the training set that owns the specified training set model.

Note that calling this function will not modify the reference count of the training set object returned by this function.

Parameters

[in] handle Handle to the MTSMODEL for which to query the owning training set.

Returns: Handle to the Minos training set that owns the MTSMODEL referenced by handle. nullptr if handle does not reference a valid MTSMODEL.

◆ GetMTSGlobalAdvance()

cvbbool_t GetMTSGlobalAdvance	(	MTS	handle,
		cvbbool_t &	useGlobalVector,
		double &	globalX,
		double &	globalY
	)

Queries the global advance vectors setting on a Minos training set.

In addition to the model-specific advance vectors a Minos training set also has a global advance vector that may be used to override the model-specific vectors. SetMTSGlobalAdvance can be used to switch between the two available options.

For a description of how the advance vectors are being used by Minos please refer to the description of ReadToken.

Parameters

[in]	handle	Handle to the Minos training set.
[out]	useGlobalVector	Flag specifying whether the global advance vector is used (`TRUE`) or if Minos is to use the model-specific advance vectors (`FALSE`).
[out]	globalX	X component of the global advance vector to set.
[out]	globalY	Y component of the global advance vector to set.

Returns: TRUE if the state has been queried successfully, FALSE if the handle does not refer to a valid Minos training set.

See also: SetMTSGlobalAdvance, GetModelAdvance, SetModelAdvance

◆ GetMTSLastFeatureWnd()

cvbbool_t GetMTSLastFeatureWnd	(	MTS	handle,
		TArea &	area
	)

Returns the feature window of the last model created for the MTS.

When writing a teach application this function may be useful for determining a sensible default feature window in interactive training.

Parameters

[in]	handle	Handle to the Minos training set.
[out]	area	`TArea` with the definition of the most recently used feature window.

Returns: TRUE if the most recently used feature window was queried successfully, FALSE if handle does not refer to a valid Minos training set.

◆ GetMTSModified()

cvbbool_t GetMTSModified	(	MTS	handle,
		cvbbool_t &	isModified
	)

Queries a training set's internal modification flag.

A Minos training set has an internal state flag that indicates whether or not there are unsaved changes in the training set. This flag is set every time a MinosCVC.dll function has been used to modify the training set's contents and it is reset every time the training set has been successfully written to a file. SetMTSModified may be used to set the flag to a selectable state.

Parameters

[in]	handle	Handle to a Minos training set.
[out]	isModified	Current state of the flag.

Returns: TRUE if the flag has been queried successfully, FALSE if handle does not refer to a valid Minos training set.

See also: SetMTSModified

◆ GetMTSSize()

intptr_t GetMTSSize ( MTS handle )

Query the memory consumption of a training set.

This function returns the number of bytes required for serializing the training set referred to by handle. This information is required for the function MTSToMemory.

Parameters

[in] handle Handle to the Minos training set.

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

See also: CLFToMemory

◆ InstanceIndex()

cvbval_t InstanceIndex ( MTSINSTANCE handle )

Returns the index of an MTSINSTANCE.

The returned value is the index that, when used with MTSInstance would return exactly the same handle with which InstanceIndex was called.

Parameters

[in] handle Handle to the MTSINSTANCE for which to query the index.

Returns: The index of the MTSINSTANCE referenced by handle in the owning training set's collection of training set instances or -1 if handle does not refer to a valid MTSINSTANCE.

◆ InstanceX()

double InstanceX ( MTSINSTANCE handle )

Retrieves the x coordinate of the position of an MTSINSTANCE.

The position refers to the MTSIMAGE that the MTSINSTANCE has been trained on.

Parameters

[in] handle Handle to an MTSINSTANCE.

Returns: x coordinate of the position of the instance referenced by handle. If handle does not refer to a valid MTSINSTANCE object the return value will be 0.0.

See also: InstanceY

◆ InstanceY()

double InstanceY ( MTSINSTANCE handle )

Retrieves the y coordinate of the position of an MTSINSTANCE.

The position refers to the MTSIMAGE that the MTSINSTANCE has been trained on.

Parameters

[in] handle Handle to an MTSINSTANCE.

Returns: y coordinate of the position of the instance referenced by handle. If handle does not refer to a valid MTSINSTANCE object the return value will be 0.0.

See also: InstanceX

◆ IsMTS()

cvbbool_t IsMTS ( MTS handle )

Verifies whether a handle refers to a valid Minos training set.

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

Parameters

[in] handle Handle to be checked.

Returns: TRUE (non-zero value) if handle refers to a valid Minos training set, FALSE otherwise.

See also: MTS, IsCLF, IsResults, IsMTSImage, IsMTSInstance, IsMTSModel

◆ IsMTSImage()

cvbbool_t IsMTSImage ( MTSIMAGE handle )

Verifies whether a handle refers to a valid Minos training set image.

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

Attention: An object referred to by an MTSIMAGE handle is not an image like the ones referred to by an IMG handle! The MTSIMAGE is a container that combines an IMG with a list of the instances that have been marked in the image and a reference to owning training set. To retrieve the IMG from an MTSIMAGE use the function GetImageFromImage.

Parameters

[in] handle Handle to be checked.

Returns: TRUE (non-zero value) if handle refers to a valid Minos training set image, FALSE otherwise.

See also: MTSIMAGE, IsCLF, IsResults, IsMTS, IsMTSInstance, IsMTSModel

◆ IsMTSInstance()

cvbbool_t IsMTSInstance ( MTSINSTANCE handle )

Verifies whether a handle refers to a valid Minos training set instance.

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

Parameters

[in] handle Handle to be checked.

Returns: TRUE (non-zero value) if handle refers to a valid Minos training set instance, FALSE otherwise.

See also: MTSINSTANCE, IsCLF, IsResults, IsMTSImage, IsMTSModel, IsMTS

◆ IsMTSModel()

cvbbool_t IsMTSModel ( MTSMODEL handle )

Verifies whether a handle refers to a valid Minos training set model.

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

Parameters

[in] handle Handle to be checked.

Returns: TRUE (non-zero value) if handle refers to a valid Minos training set model, FALSE otherwise.

See also: MTSMODEL, IsCLF, IsResults, IsMTSImage, IsMTSInstance, IsMTS

◆ LearnCLFFromMTS()

cvbbool_t LearnCLFFromMTS	(	MTS	handle,
		const char *	pstrMTSName,
		TLearnControlStructure	lcs,
		CLF &	clfHandle
	)

Creates a Minos classifier from a Minos training set.

In short, the classifier generation is carried out like this:

Minos analyzes the first instance of the first model and extracts a reasonable set of features from it. These features are added to a proto-classifier.
With this proto-classifier Minos searches all regions in the training set images that are neither occupied by an instance of the currently trained model nor marked as don't care regions. Anything that is found in those regions is by definition a false positive. If a false positive is found, Minos goes back to the currently processed instance and adds more features to the proto-classifier. This is repeated until step 2 no longer turns up false positives.
After that, Minos will look at the next instance of the currently processed model. If the instance is recognized correctly with the current proto-classifier, Minos will advance to the next instance (until all the instances of the currently processed model have been processed). Otherwise, Minos will extract more features based on the current instance and add the to the current proto-classifier, then go back to step 2.
Once all instances of the currently processed model have been processed Minos will advance to the next model and start at step one. This is repeated until all models have been processed.

Attention: The classifier returned by this function is not yet fully functional. Before using the newly generated classifier in a search or read operation, please call SetCLFQualityType on it.

Parameters

[in]	handle	Handle to the Minos training set to train the classifier from.
[in]	pstrMTSName	Pointer to a zero terminated string giving a name for the training set. This string will become an immutable property of the classifier and may e.g. be used for specifying the file name of the training set from which a classifier was generated.
[in]	lcs	TLearnControlStructure that specifies various parameters for the learning process. See the documentation of TLearnControlStructure for a description of the available options.
[out]	clfHandle	Will receive the handle to the newly generated Minos classifier. Remember to dispose of this classifier with `ReleaseObject` (CVCImg.dll) once it is no longer needed.

Returns

TRUE if a new classifier was generated successfully, FALSE otherwise. Possible error conditions are:

handle doe not refer to a valid Minos training set.
an out of memory situation occurred

See also: CLF, MTS

◆ LearnCLFFromMTSW()

cvbbool_t LearnCLFFromMTSW	(	MTS	handle,
		const wchar_t *	pstrMTSName,
		TLearnControlStructure	lcs,
		CLF &	clfHandle
	)

Creates a Minos classifier from a Minos training set.

In short, the classifier generation is carried out like this:

Minos analyzes the first instance of the first model and extracts a reasonable set of features from it. These features are added to a proto-classifier.
With this proto-classifier Minos searches all regions in the training set images that are neither occupied by an instance of the currently trained model nor marked as don't care regions. Anything that is found in those regions is by definition a false positive. If a false positive is found, Minos goes back to the currently processed instance and adds more features to the proto-classifier. This is repeated until step 2 no longer turns up false positives.
After that, Minos will look at the next instance of the currently processed model. If the instance is recognized correctly with the current proto-classifier, Minos will advance to the next instance (until all the instances of the currently processed model have been processed). Otherwise, Minos will extract more features based on the current instance and add the to the current proto-classifier, then go back to step 2.
Once all instances of the currently processed model have been processed Minos will advance to the next model and start at step one. This is repeated until all models have been processed.

Attention: The classifier returned by this function is not yet fully functional. Before using the newly generated classifier in a search or read operation, please call SetCLFQualityType on it.

Parameters

[in]	handle	Handle to the Minos training set to train the classifier from.
[in]	pstrMTSName	Pointer to a zero terminated string giving a name for the training set. This string will become an immutable property of the classifier and may e.g. be used for specifying the file name of the training set from which a classifier was generated.
[in]	lcs	TLearnControlStructure that specifies various parameters for the learning process. See the documentation of TLearnControlStructure for a description of the available options.
[out]	clfHandle	Will receive the handle to the newly generated Minos classifier. Remember to dispose of this classifier with `ReleaseObject` (CVCImg.dll) once it is no longer needed.

Returns

TRUE if a new classifier was generated successfully, FALSE otherwise. Possible error conditions are:

handle doe not refer to a valid Minos training set.
an out of memory situation occurred

See also: CLF, MTS

◆ LoadMTSFile()

cvbbool_t LoadMTSFile	(	const char *	pstrFileName,
		MTS &	mts
	)

Loads a Minos training set from a file.

If the function succeeds, the handle returned in the mts parameter will point to the newly loaded Minos training set.

All Minos training sets 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 training set by calling ReleaseObject on it once it is no longer needed.

Note that this function will be able to load the training set 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

[in]	pstrFileName	Pointer to a zero-terminated string with the full path to the file.
[out]	mts	If the file was loaded successfully, this parameter will receive the handle to the loaded training set.

Returns: TRUE on success, FALSE if any error occurs.

See also: LoadMTSFileW, WriteMTSFile, WriteCLFFileW, WriteMTSFileEx, WriteCLFFileExW

◆ LoadMTSFileW()

cvbbool_t LoadMTSFileW	(	const wchar_t *	pstrFileName,
		MTS &	mts
	)

Loads a Minos training set from a file.

If the function succeeds, the handle returned in the mts parameter will point to the newly loaded Minos training set.

All Minos training sets 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 training set by calling ReleaseObject on it once it is no longer needed.

Note that this function will be able to load the training set 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

[in]	pstrFileName	Pointer to a zero-terminated string with the full path to the file.
[out]	mts	If the file was loaded successfully, this parameter will receive the handle to the loaded training set.

Returns: TRUE on success, FALSE if any error occurs.

See also: LoadMTSFile, WriteMTSFile, WriteCLFFileW, WriteMTSFileEx, WriteCLFFileExW

◆ MemoryToMTS()

cvbbool_t MemoryToMTS	(	void *	memory,
		size_t	capacity,
		MTS &	mts
	)

Deserialize a classifier that was previously serialized with MTSToMemory.

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

Parameters

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

Returns

TRUE if the training set 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 training set.

See also: MTSToMemory, GetMTSSize

◆ MTSComment()

char * MTSComment ( MTS handle )

Returns a pointer to the training set's comment string.

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

Parameters

[in] handle Handle of the Minos training set to be queried.

Returns

Pointer to the training set's comment string if handle refers to a valid Minos training set, 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 training set 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: SetMTSComment, SetMTSCommentW, MTSCommentW

◆ MTSCommentW()

const wchar_t * MTSCommentW ( MTS handle )

Returns a pointer to the training set's comment string.

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

Since: Common Vision Blox 13.00.000

Parameters

[in] handle Handle of the Minos training set to be queried.

Returns

Pointer to the training set's comment string if handle refers to a valid Minos training set, nullptr otherwise.
The returned pointer is a pointer to an internal string in the training set 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: SetMTSComment, SetMTSCommentW, MTSComment

◆ MTSConsistencyCheck()

cvbbool_t MTSConsistencyCheck	(	MTS	handle,
		double	threshold,
		cvbdensity_t	density,
		TFCheckProgress	progress,
		void *	pPrivate,
		RESULTS &	results
	)

Performs a consistency check on the entire training set to find instances that might have been forgotten in the training process.

As Minos treats all regions inside an MTSIMAGE that have neither been marked as objects to be trained nor as regions to be ignored as implicit counter sample to all the trained instances it is very important that all the objects inside an image are actually marked as instances or as don't care regions. Failure to do so will quickly lead to a classifier that struggles to identify the trained objects correctly as it has been generated on contradicting information.

One way to prevent this is to run a consistency check on the training set. During this kind of consistency check Minos will loop through the model images (GetImageFromModel) of all models that have been trained and loop through all the MTSIMAGE objects in the training set. In those loops, the model image of the currently processed model will be use as a correlation template in an OptCorrelations call. All the results that are encountered in this call whose correlation result exceeds the threshold parameter's value are compared against the list of instances marked on the currently processed image. If they lie too close to a marked instance (as defined by the expectation radius currently set on the training set; see GetMTSCorelParams and SetMTSCorelParams) or if their location has been marked as a don't care region then the correlation result will be discarded.

All remaining correlation results from this nested loop by virtue of the way they have been extracted indicate locations in the training set images that resemble a trained model more or less strongly and might be worth having a second look at whether or not they should be included in the training set's instances.

Due to the number of calculations involved a consistency check is a fairly time-consuming operation, especially so when carried out on an entire training set. When taking too long, it may be interrupted via the progress callback.

Parameters

[in]	handle	Handle to the Minos training set on which to run the consistency check.
[in]	threshold	Correlation threshold to be used in the OptCorrelations call. Only correlation results above this threshold are eligible for entering the `results` list.
[in]	density	Scan density to apply when searching for forgotten instances. 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 deteriorating the search results). Note that this scan density does not only apply to the sliding of the template over the area of interest, but also to the calculation of the normalized gray scale correlation itself!
[in]	progress	Callback pointer to a function with the signature defined by TFCheckProgress. This function will be called after every processed line, giving progress updates on the consistency check and providing a chance for the callee to interrupt the entire process.
[in]	pPrivate	Pointer to user-defined data that will be passed to the `progress` callback.
[out]	results	Receives a handle to a Minos result lists. The results in this list are locations in the training set images that might have been overlooked during training and should potentially be added to the training set. As usual, RESULTS list may be processed using the functions SearchResultsCount and SearchResult or SearchResultW. Remember to dispose of this list with a call to `ReleaseObject` (CVCImg.dll) once it is no longer needed!

Returns

TRUE if the consistency check was carried out successfully, FALSE otherwise. Possible error conditions are:

handle does not refer to a valid Minos training set
the consistency check was interrupted

See also: MTSImageCheck, MTSModelCheck, MTSModelImageCheck

◆ MTSImage()

MTSIMAGE MTSImage	(	MTS	handle,
		cvbval_t	index
	)

Returns a handle of one of the MTSIMAGE objects in a training set.

The MTSIMAGE objects in a Minos training set are accessed via their index which ranges from 0 to NumMTSImages(handle) - 1.

Attention: An object referred to by an MTSIMAGE handle is not an image like the ones referred to by an IMG handle! The MTSIMAGE is a container that combines an IMG with a list of the instances that have been marked in the image and a reference to owning training set. To retrieve the IMG from an MTSIMAGE use the function GetImageFromImage.

Parameters

[in]	handle	Handle to the Minos training set to be queried.
[in]	index	Index of the MTSIMAGE to retrieve (must be in the range [0...`NumMTSModels(handle) - 1`].

Returns

Handle to the queried MTSIMAGE or nullptr if an error occurred. Typical error conditions are:

handle does not refer to a valid Minos training set.
index is outside the range [0...NumMTSImages(handle) - 1].

Note that MTSImage does not modify the reference count of the retrieved handle! It is therefore not necessary to call ReleaseObject on it once it is no longer needed as the ownership by default lies with training set the image belongs to.

See also: NumMTSImages, IsMTSImage

◆ MTSImageCheck()

cvbbool_t MTSImageCheck	(	MTSIMAGE	handle,
		double	threshold,
		cvbdensity_t	density,
		TFCheckProgress	progress,
		void *	pPrivate,
		RESULTS &	results
	)

Performs a consistency check on a training set image to find instances that might have been forgotten in the training process.

As Minos treats all regions inside an MTSIMAGE that have neither been marked as objects to be trained nor as regions to be ignored as implicit counter sample to all the trained instances it is very important that all the objects inside an image are actually marked as instances or as don't care regions. Failure to do so will quickly lead to a classifier that struggles to identify the trained objects correctly as it has been generated on contradicting information.

One way to prevent this is to run a consistency check on the training set image. During this kind of consistency check Minos will loop through the model images (GetImageFromModel) of all models that have been trained and use them as a correlation template in an OptCorrelations call. All the results that are encountered in this call whose correlation result exceeds the threshold parameter's value are compared against the list of instances marked on the image. If they lie too close to a marked instance (as defined by the expectation radius currently set on the training set; see GetMTSCorelParams and SetMTSCorelParams) or if their location has been marked as a don't care region then the correlation result will be discarded.

All remaining correlation results from this loop by virtue of the way they have been extracted indicate locations in the training set image that resemble a trained model more or less strongly and might be worth having a second look at whether or not they should be included in the training set's instances.

Due to the number of calculations involved a consistency check is a fairly time-consuming operation. When taking too long, it may be interrupted via the progress callback.

Parameters

[in]	handle	Handle to the Minos training set image on which to run the consistency check.
[in]	threshold	Correlation threshold to be used in the OptCorrelations call. Only correlation results above this threshold are eligible for entering the `results` list.
[in]	density	Scan density to apply when searching for forgotten instances. 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 deteriorating the search results). Note that this scan density does not only apply to the sliding of the template over the area of interest, but also to the calculation of the normalized gray scale correlation itself!
[in]	progress	Callback pointer to a function with the signature defined by TFCheckProgress. This function will be called after every processed line, giving progress updates on the consistency check and providing a chance for the callee to interrupt the entire process.
[in]	pPrivate	Pointer to user-defined data that will be passed to the `progress` callback.
[out]	results	Receives a handle to a Minos result lists. The results in this list are locations in the training set image that might have been overlooked during training and should potentially be added to the training set. As usual, RESULTS list may be processed using the functions SearchResultsCount and SearchResult or SearchResultW. Remember to dispose of this list with a call to `ReleaseObject` (CVCImg.dll) once it is no longer needed!

Returns

TRUE if the consistency check was carried out successfully, FALSE otherwise. Possible error conditions are:

handle does not refer to a valid Minos training set image
the consistency check was interrupted

See also: MTSConsistencyCheck, MTSModelCheck, MTSModelImageCheck

◆ MTSImageIndex()

cvbval_t MTSImageIndex ( MTSIMAGE handle )

Returns the index of an MTSIMAGE.

The returned value is the index that, when used with MTSImage would return exactly the same handle with which MTSImageIndex was called.

Parameters

[in] handle Handle to the MTSIMAGE for which to query the index.

Returns: The index of the MTSIMAGE referenced by handle in the owning training set's collection of training set images or -1 if handle does not refer to a valid MTSIMAGE.

See also: MTSImage

◆ MTSImageInstance()

MTSINSTANCE MTSImageInstance	(	MTSIMAGE	handle,
		cvbval_t	index
	)

Returns a handle to an instance in a MTSIMAGE.

The instances that have been marked in a MTSIMAGE are referred to by indices running from 0 to NumMTSImageInstances - 1.

Parameters

[in]	handle	Handle to the MTSIMAGE.
[in]	index	Index of the MTSINSTANCE to be retrieved. Must be in range [0...NumMTSImageInstances(handle) - 1].

Returns

Handle to the referenced instance or nullptr if an error occurred. Typical error conditions are:

handle does not refer to a valid MTSIMAGE.
index is not on the range [0...NumMTSImageInstances(handle) - 1]

Note that MTSImageInstance does not modify the reference count of the retrieved handle! It is therefore not necessary to call ReleaseObject on it once it is no longer needed as the ownership by default lies with training set the instance belongs to.

◆ MTSInstance()

MTSINSTANCE MTSInstance	(	MTS	handle,
		cvbval_t	index
	)

Returns a handle of one of the MTSINSTANCE objects in a training set.

The MTSINSTANCE objects in a Minos training set are accessed via their index which ranges from 0 to NumMTSInstances(handle) - 1.

Parameters

[in]	handle	Handle to the Minos training set to be queried.
[in]	index	Index of the MTSINSTANCE to retrieve (must be in the range [0...`NumMTSInstances(handle) - 1`].

Returns

Handle to the queried MTSINSTANCE or nullptr if an error occurred. Typical error conditions are:

handle does not refer to a valid Minos training set.
index is outside the range [0...NumMTSInstances(handle) - 1].

Note that MTSInstance does not modify the reference count of the retrieved handle! It is therefore not necessary to call ReleaseObject on it once it is no longer needed as the ownership by default lies with training set the image belongs to.

See also: NumMTSInstances, IsMTSInstance

◆ MTSModel()

MTSMODEL MTSModel	(	MTS	handle,
		cvbval_t	index
	)

Returns a handle of one of the MTSMODEL objects in a training set.

The MTSMODEL objects in a Minos training set are accessed via their index which ranges from 0 to NumMTSModels(handle) - 1.

Parameters

[in]	handle	Handle to the Minos training set to be queried.
[in]	index	Index of the MTSMODEL to retrieve (must be in the range [0...`NumMTSModels(handle) - 1`].

Returns

Handle to the queried MTSMODEL or nullptr if an error occurred. Typical error conditions are:

handle does not refer to a valid Minos training set.
index is outside the range [0...NumMTSModels(handle) - 1].

Note that MTSModel does not modify the reference count of the retrieved handle! It is therefore not necessary to call ReleaseObject on it once it is no longer needed as the ownership by default lies with training set the image belongs to.

See also: NumMTSModels, IsMTSModel

◆ MTSModelCheck()

cvbbool_t MTSModelCheck	(	MTSMODEL	handle,
		double	threshold,
		cvbdensity_t	density,
		TFCheckProgress	progress,
		void *	pPrivate,
		RESULTS &	results
	)

Performs a consistency check with a specific model on the entire training set to find instances that might have been forgotten in the training process.

As Minos treats all regions inside an MTSIMAGE that have neither been marked as objects to be trained nor as regions to be ignored as implicit counter sample to all the trained instances it is very important that all the objects inside an image are actually marked as instances or as don't care regions. Failure to do so will quickly lead to a classifier that struggles to identify the trained objects correctly as it has been generated on contradicting information.

One way to prevent this is to run a consistency check on the training set. During this kind of consistency check Minos will use the model image (GetImageFromModel) of the specified model and loop through all the MTSIMAGE objects in the training set. In this loops, the model image will be use as a correlation template in an OptCorrelations call. All the results that are encountered in this call whose correlation result exceeds the threshold parameter's value are compared against the list of instances marked on the currently processed image. If they lie too close to a marked instance (as defined by the expectation radius currently set on the training set; see GetMTSCorelParams and SetMTSCorelParams) or if their location has been marked as a don't care region then the correlation result will be discarded.

All remaining correlation results from this loop by virtue of the way they have been extracted indicate locations in the training set images that resemble the specified model more or less strongly and might be worth having a second look at whether or not they should be included in the training set's instances.

Due to the number of calculations involved a consistency check is a fairly time-consuming operation, especially so when carried out on an entire training set. When taking too long, it may be interrupted via the progress callback.

Parameters

[in]	handle	Handle to the Minos training set model with which to run the consistency check on the owning training set.
[in]	threshold	Correlation threshold to be used in the OptCorrelations call. Only correlation results above this threshold are eligible for entering the `results` list.
[in]	density	Scan density to apply when searching for forgotten instances. 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 deteriorating the search results). Note that this scan density does not only apply to the sliding of the template over the area of interest, but also to the calculation of the normalized gray scale correlation itself!
[in]	progress	Callback pointer to a function with the signature defined by TFCheckProgress. This function will be called after every processed line, giving progress updates on the consistency check and providing a chance for the callee to interrupt the entire process.
[in]	pPrivate	Pointer to user-defined data that will be passed to the `progress` callback.
[out]	results	Receives a handle to a Minos result list. The results in this list are locations in the training set images that might have been overlooked during training and should potentially be added to the training set. As usual, RESULTS list may be processed using the functions SearchResultsCount and SearchResult or SearchResultW. Remember to dispose of this list with a call to `ReleaseObject` (CVCImg.dll) once it is no longer needed!

Returns

TRUE if the consistency check was carried out successfully, FALSE otherwise. Possible error conditions are:

handle does not refer to a valid Minos training set
the consistency check was interrupted

See also: MTSImageCheck, MTSConsistencyCheck, MTSModelImageCheck

◆ MTSModelImageCheck()

cvbbool_t MTSModelImageCheck	(	MTSMODEL	modelHandle,
		MTSIMAGE	imageHandle,
		double	threshold,
		cvbdensity_t	density,
		TFCheckProgress	progress,
		void *	pPrivate,
		RESULTS &	results
	)

Performs a consistency check with a specific model on a specific training set image to find instances that might have been forgotten in the training process.

As Minos treats all regions inside an MTSIMAGE that have neither been marked as objects to be trained nor as regions to be ignored as implicit counter sample to all the trained instances it is very important that all the objects inside an image are actually marked as instances or as don't care regions. Failure to do so will quickly lead to a classifier that struggles to identify the trained objects correctly as it has been generated on contradicting information.

One way to prevent this is to run a consistency check. During this kind of consistency check Minos will use the model image (GetImageFromModel) of the specified model and use it as a correlation template in an OptCorrelations call on the specified MTSIMAGE. All the results that are encountered in this call whose correlation result exceeds the threshold parameter's value are compared against the list of instances marked on the image. If they lie too close to a marked instance (as defined by the expectation radius currently set on the training set; see GetMTSCorelParams and SetMTSCorelParams) or if their location has been marked as a don't care region then the correlation result will be discarded.

All remaining correlation results from this call by virtue of the way they have been extracted indicate locations in the training set image that resemble the specified model more or less strongly and might be worth having a second look at whether or not they should be included in the training set's instances.

Due to the number of calculations involved a consistency check is a fairly time-consuming operation, especially so when carried out on an entire training set. When taking too long, it may be interrupted via the progress callback.

Parameters

[in]	modelHandle	Handle to the Minos training set model with which to run the consistency check.
[in]	imageHandle	Handle to the Minos training set image on which to run the consistency check.
[in]	threshold	Correlation threshold to be used in the OptCorrelations call. Only correlation results above this threshold are eligible for entering the `results` list.
[in]	density	Scan density to apply when searching for forgotten instances. 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 deteriorating the search results). Note that this scan density does not only apply to the sliding of the template over the area of interest, but also to the calculation of the normalized gray scale correlation itself!
[in]	progress	Callback pointer to a function with the signature defined by TFCheckProgress. This function will be called after every processed line, giving progress updates on the consistency check and providing a chance for the callee to interrupt the entire process.
[in]	pPrivate	Pointer to user-defined data that will be passed to the `progress` callback.
[out]	results	Receives a handle to a Minos result list. The results in this list are locations in the training set image that might have been overlooked during training and should potentially be added to the training set. As usual, RESULTS list may be processed using the functions SearchResultsCount and SearchResult or SearchResultW. Remember to dispose of this list with a call to `ReleaseObject` (CVCImg.dll) once it is no longer needed!

Returns

TRUE if the consistency check was carried out successfully, FALSE otherwise. Possible error conditions are:

handle does not refer to a valid Minos training set
the consistency check was interrupted

See also: MTSImageCheck, MTSModelCheck, MTSConsistencyCheck

◆ MTSModelIndex()

cvbval_t MTSModelIndex ( MTSMODEL handle )

Returns the index of an MTSMODEL.

The returned value is the index that, when used with MTSModel would return exactly the same handle with which MTSModelIndex was called.

Parameters

[in] handle Handle to the MTSMODEL for which to query the index.

Returns: The index of the MTSMODEL referenced by handle in the owning training set's collection of training set images or -1 if handle does not refer to a valid MTSMODEL

◆ MTSModelInstance()

MTSINSTANCE MTSModelInstance	(	MTSMODEL	handle,
		cvbval_t	index
	)

Returns a handle to an instance in a MTSMODEL.

The instances that have been added to a MTSMODEL are referred to by indices running from 0 to NumMTSModelInstances - 1.

Parameters

[in]	handle	Handle to the MTSMODEL.
[in]	index	Index of the MTSINSTANCE to be retrieved. Must be in range [0...NumMTSModelInstances(handle) - 1].

Returns

Handle to the referenced instance or nullptr if an error occurred. Typical error conditions are:

handle does not refer to a valid MTSMODEL.
index is not on the range [0...NumMTSModelInstances(handle) - 1]

Note that MTSModelInstance does not modify the reference count of the retrieved handle! It is therefore not necessary to call ReleaseObject on it once it is no longer needed as the ownership by default lies with training set the instance belongs to.

◆ MTSToMemory()

cvbbool_t MTSToMemory	(	MTS	handle,
		void *	memory,
		size_t	capacity
	)

Serialize a Minos training set into a memory buffer.

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

Parameters

[in]	handle	Handle to the Minos training set to be serialized.
[in]	memory	Points to the beginning of the memory block to which the training set should be serialized.
[in]	capacity	Size of the memory block pointed to by `memory` available for serialization. Use GetMTSSize 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 training set
no Minos license is available on the system
capacity is less than the return value of GetMTSSize

See also: MemoryToMTS, GetMTSSize

Example: Serialize a Minos training set into a block of memory and restore it
// assumptions:

// - mts points to a valid Minos training set

auto numBytes = GetMTSSize(mts);

if (numBytes <= 0)

return false;

// note: might as well use malloc() here, but std::vector is self-cleaning

std::vector<uin8_t> buffer(numBytes);

MTSToMemory(mts, buffer.data(), buffer.size());

MTS mts2 = nullptr;

MemoryToMTS(buffer.data(), buffer.size(), mts2);

... // (do something with mts2)

ReleaseObject(mts2);

MTS
void * MTS
Handle to a Minos training set.
Definition: iMinosCVC.h:39

MemoryToMTS
cvbbool_t MemoryToMTS(void *memory, size_t capacity, MTS &mts)
Deserialize a classifier that was previously serialized with MTSToMemory.
Definition: MinosTeachExport.cpp:593

MTSToMemory
cvbbool_t MTSToMemory(MTS handle, void *memory, size_t capacity)
Serialize a Minos training set into a memory buffer.
Definition: MinosTeachExport.cpp:543

GetMTSSize
intptr_t GetMTSSize(MTS handle)
Query the memory consumption of a training set.
Definition: MinosTeachExport.cpp:489

◆ MTSTransform()

cvbbool_t MTSTransform	(	MTS	inputMts,
		TMatrix	matrix,
		MTS &	outputMts
	)

Geometrically transform an entire Minos training set.

MTSTransform works almost identical to TransformMTSImage: It uses a 2x2 matrix to geometrically transform all images inside a Minos training set (effectively by calling TransformMTSImage for every MTSIMAGE in a Minos training set). Like with TransformMTSImage, the positions of all the MTSINSTANCE objects from the original MTSIMAGE objects are transformed as well and will also be added to the resulting training.

On locations where the correlation test fails on the transformed instances (see CreateMTS, SetMTSCorelParams, GetMTSCorelParams) new models with the same pattern name and feature window as the original MTSINSTANCE will be created. To suppress the creation of new instances entirely, set the correlation threshold to 0.0 prior to calling MTSTransform (SetMTSCorelParams).

Parameters

[in]	inputMts	Handle to the Minos training set of which to create a transformed copy.
[in]	matrix	2x2 matrix to transform the training set with.
[out]	outputMts	Receives the handle to the transformed training set. Remember to dispose of this training set with `ReleaseObject` (CVCImg.dll) once it is no longer needed.

Returns

TRUE if the function completed successfully, FALSE otherwise. Possible reasons for failure are:

inputMTS does not refer to a valid Minos Training Set object.
An out of memory situation occurred.

See also: Rotation or size-independent classifiers

◆ MTSVerifyToken()

cvbbool_t MTSVerifyToken	(	MTS	handle,
		IMG	image,
		cvbdim_t	index,
		TArea	area,
		TArea	translatedArea,
		double	corThresh,
		const char *	pstrToken,
		double &	minCor,
		cvbval_t &	count
	)

Verifies OCR using normalized gray scale correlation.

MTSVerifyToken works similar to ReadToken in that it also uses Minos' built-in advance vector mechanism (see ReadToken for details). However, MTSVerifyToken does not read a string but rather compares it versus an expected string: The pstrToken string defines the sequence of model images that will be used in the correlation calculations during the verification process:

First, OptCorrelation will be used in area with the model named pstrToken[0] as the correlation template.
The found optimum position will be offset by that model's advance vector and the translatedArea, then OptCorrelation will be called with the model image of the model name pstrToken[1] as the correlation template.
The whole process will be repeated until the terminating zero in pstrToken is hit.

Attention: MTSVerifyToken will produce undefined behavior when used with a Minos training set in which model names are longer than 1 character.

Parameters

[in]	handle	Handle to the Minos training set to be used for the verification operation.
[in]	image	Image in which to perform the verification operation.
[in]	index	Plane index in the `image` in which to perform the verification operation. Must be in the range [0...ImageDimension(image) - 1].
[in]	area	Area of interest in which to start the verification.
[in]	translatedArea	Area of interest for the subsequent verification steps (see also documentation of ReadToken).
[in]	corThresh	Minimum correlation to achieve at each verification step. If no hit was found that exceeds this threshold, the verification process will stop.
[in]	pstrToken	Expected character sequence.
[out]	minCor	Minimum correlation encountered during the verification.
[out]	count	Number of steps after which the verification stopped cannot exceed `strlen(pstrToken)`.

Returns: TRUE if the verification was carried out successfully, FALSE otherwise.

◆ MTSVerifyTokenW()

cvbbool_t MTSVerifyTokenW	(	MTS	handle,
		IMG	image,
		cvbdim_t	index,
		TArea	area,
		TArea	translatedArea,
		double	corThresh,
		const wchar_t *	pstrToken,
		double &	minCor,
		cvbval_t &	count
	)

Verifies OCR using normalized gray scale correlation.

MTSVerifyToken works similar to ReadToken in that it also uses Minos' built-in advance vector mechanism (see ReadToken for details). However, MTSVerifyToken does not read a string but rather compares it versus an expected string: The pstrToken string defines the sequence of model images that will be used in the correlation calculations during the verification process:

First, OptCorrelation will be used in area with the model named pstrToken[0] as the correlation template.
The found optimum position will be offset by that model's advance vector and the translatedArea, then OptCorrelation will be called with the model image of the model name pstrToken[1] as the correlation template.
The whole process will be repeated until the terminating zero in pstrToken is hit.

Attention: MTSVerifyToken will produce undefined behavior when used with a Minos training set in which model names are longer than 1 character.

Parameters

[in]	handle	Handle to the Minos training set to be used for the verification operation.
[in]	image	Image in which to perform the verification operation.
[in]	index	Plane index in the `image` in which to perform the verification operation. Must be in the range [0...ImageDimension(image) - 1].
[in]	area	Area of interest in which to start the verification.
[in]	translatedArea	Area of interest for the subsequent verification steps (see also documentation of ReadToken).
[in]	corThresh	Minimum correlation to achieve at each verification step. If no hit was found that exceeds this threshold, the verification process will stop.
[in]	pstrToken	Expected character sequence.
[out]	minCor	Minimum correlation encountered during the verification.
[out]	count	Number of steps after which the verification stopped cannot exceed `strlen(pstrToken)`.

Returns: TRUE if the verification was carried out successfully, FALSE otherwise.

◆ NewMTSImage()

MTSIMAGE NewMTSImage	(	MTS	handle,
		IMG	image
	)

Creates a new MTSIMAGE and adds it to a Minos training set.

The new MTSIMAGE object in the Minos training set is generated based on the Common Vision Blox image passed in the image parameter and a handle to the newly created image is returned

Attention: NewMTSImage fails for color (multi-plane) images. If you need to create a new MTS imag based on a multi-plane image use NewMTSImageIndex instead.

Parameters

[in]	handle	Handle to the Minos training set to which to add the new MTSIMAGE.
[in]	image	Handle to the image from which to create the new MTSIMAGE. Must not have more than one image plane.

Returns: If the creation of the new MTSIMAGE succeeded, a handle to the newly created object will be returned. Otherwise the return value is a nullptr. Note that it is not necessary to call ReleaseObject on the returned handle it once it is no longer needed as the ownership lies with the training set to which the image has been added.

See also: NewMTSImageIndex

◆ NewMTSImageIndex()

MTSIMAGE NewMTSImageIndex	(	MTS	handle,
		IMG	image,
		cvbval_t	index
	)

Creates a new MTSIMAGE and adds it to a Minos training set.

The new MTSIMAGE object in the Minos training set is generated based on the Common Vision Blox image passed in the image parameter and a handle to the newly created image is returned

Parameters

[in]	handle	Handle to the Minos training set to which to add the new MTSIMAGE.
[in]	image	Handle to the image from which to create the new MTSIMAGE.
[in]	index	Index of the `image` plane from which to create the new MTSIMAGE.

Returns: If the creation of the new MTSIMAGE succeeded, a handle to the newly created object will be returned. Otherwise the return value is a nullptr. Note that it is not necessary to call ReleaseObject on the returned handle it once it is no longer needed as the ownership lies with the training set to which the image has been added.

See also: NewMTSImage

◆ NewMTSInstance()

cvbbool_t NewMTSInstance	(	MTSIMAGE	image,
		const char *	pstrName,
		cvbbool_t	askForce,
		double &	xPos,
		double &	yPos,
		MTSINSTANCE &	instance
	)

Create a new sample instance for a pattern class.

This function may be used on an existing MTSIMAGE to define a new instance of a model class. The model class in this case is only referenced by name - if several models with identical names (i.e. a class) exist, the best match will be determined by the highest correlation match of the position indicated by (xPos, yPos) versus the model images (GetImageFromModel) of all the models that have the same name.

The correlation will be calculated using the function OptCorrelation on an area of interest around (xPos, yPos) defined by the expectation radius property of the training set (see SetMTSCorelParams and CreateMTS). The ultimate instance position may be modified by the correlation results as described in the documentation of CreateMTS.

If the correlation result does not exceed the correlation threshold property of the training set (again, see SetMTSCorelParams and CreateMTS) and the askForce parameter is TRUE, then this function will open a message box and prompt the user to confirm the addition of a new instance despite the low correspondence with the previously trained instances. If askForce is FALSE no new instance will be created, the function will set instance to nullptr and return TRUE.

If no model with the name passed in pstrName is available in the training set, NewMTSInstance will return FALSE - in this case please use NewMTSModel to create a new model instead.

Parameters

[in]	image	Handle to the MTSIMAGE from which to train the new instance.
[in]	pstrName	Pointer to a zero terminated string specifying the class name to which to add the new instance.
[in]	askForce	Flag controlling the response to a failed correlation test. If `askForce` is `TRUE`, a message box will appear after a failed correlation check asking if the user how to proceed with the instance generation attempt.
[in,out]	xPos	X position of the sample. Might be modified by the correlation check if the expectation radius is greater than zero - in that case, `NewMTSInstance` will return the final instance position in this parameter.
[in,out]	yPos	Y position of the sample. Might be modified by the correlation check if the expectation radius is greater than zero - in that case, `NewMTSInstance` will return the final instance position in this parameter.
[out]	instance	Will receive the handle to the newly created MTSINSTANCE if instance generation was successful. May be overwritten with a `nullptr` if instance generation failed. It is not necessary to call `ReleaseObject` on the handle returned here as the ownership of the newly created instance by default lies only with the model to which the instance has been added.

Returns

TRUE if the call was successful, FALSE otherwise. Note that a return value of TRUE does not imply that a new MTSINSTANCE has been created by the NewMTSInstace call. To check whether a new MTSINSTANCE was created check the value returned in instance. Possible reasons for failure include

image does not refer to a valid MTSIMAGE object
the training set does not contain a model by the name passed in pstrName
the xPos or yPos parameter is not compatible with the size of the MTSIMAGE

◆ NewMTSInstanceW()

cvbbool_t NewMTSInstanceW	(	MTSIMAGE	image,
		const wchar_t *	pstrName,
		cvbbool_t	askForce,
		double &	xPos,
		double &	yPos,
		MTSINSTANCE &	instance
	)

Create a new sample instance for a pattern class.

This function may be used on an existing MTSIMAGE to define a new instance of a model class. The model class in this case is only referenced by name - if several models with identical names (i.e. a class) exist, the best match will be determined by the highest correlation match of the position indicated by (xPos, yPos) versus the model images (GetImageFromModel) of all the models that have the same name.

The correlation will be calculated using the function OptCorrelation on an area of interest around (xPos, yPos) defined by the expectation radius property of the training set (see SetMTSCorelParams and CreateMTS). The ultimate instance position may be modified by the correlation results as described in the documentation of CreateMTS.

If the correlation result does not exceed the correlation threshold property of the training set (again, see SetMTSCorelParams and CreateMTS) and the askForce parameter is TRUE, then this function will open a message box and prompt the user to confirm the addition of a new instance despite the low correspondence with the previously trained instances. If askForce is FALSE no new instance will be created, the function will set instance to nullptr and return TRUE.

If no model with the name passed in pstrName is available in the training set, NewMTSInstance will return FALSE - in this case please use NewMTSModel to create a new model instead.

Since: Common Vision Blox 13.00.000.

Parameters

[in]	image	Handle to the MTSIMAGE from which to train the new instance.
[in]	pstrName	Pointer to a zero terminated string specifying the class name to which to add the new instance.
[in]	askForce	Flag controlling the response to a failed correlation test. If `askForce` is `TRUE`, a message box will appear after a failed correlation check asking if the user how to proceed with the instance generation attempt.
[in,out]	xPos	X position of the sample. Might be modified by the correlation check if the expectation radius is greater than zero - in that case, `NewMTSInstance` will return the final instance position in this parameter.
[in,out]	yPos	Y position of the sample. Might be modified by the correlation check if the expectation radius is greater than zero - in that case, `NewMTSInstance` will return the final instance position in this parameter.
[out]	instance	Will receive the handle to the newly created MTSINSTANCE if instance generation was successful. May be overwritten with a `nullptr` if instance generation failed. It is not necessary to call `ReleaseObject` on the handle returned here as the ownership of the newly created instance by default lies only with the model to which the instance has been added.

Returns

TRUE if the call was successful, FALSE otherwise. Note that a return value of TRUE does not imply that a new MTSINSTANCE has been created by the NewMTSInstace call. To check whether a new MTSINSTANCE was created check the value returned in instance. Possible reasons for failure include

image does not refer to a valid MTSIMAGE object
the training set does not contain a model by the name passed in pstrName
the xPos or yPos parameter is not compatible with the size of the MTSIMAGE

◆ NewMTSModel()

MTSMODEL NewMTSModel	(	MTSIMAGE	handle,
		const char *	pstrName,
		double	xPos,
		double	yPos,
		TArea	area
	)

Creates a new pattern model.

A new model is defined as the combination of a model name, a pattern position inside and image and a feature window/extent relative to the pattern position.

Attention: Even though of double precision, xPos yPos should be integer numbers. Any fractional parts of the values passed in xPos or yPos will be rounded.

Parameters

[in]	handle	Handle to the MTSIMAGE from which the first instance of the new model is to be trained.
[in]	pstrName	Name of the new pattern model. Note that pattern do not have to be unique in Minos.
[in]	xPos	X coordinate of the first instance.
[in]	yPos	Y coordinate of the first instance.
[in]	area	Feature window extent for the new pattern model. The feature window is the smallest rectangle sufficient to recognize the pattern on the basis of its contents. It must be an axis-parallel rectangle with integer coordinates containing the point (0,0), and the left and top coordinates are therefore usually less than or equal to zero.

Returns

Handle to the newly generated model if model generation succeeded, nullptr otherwise. Typical error conditions are:

handle does not refer to a valid MTSIMAGE object
at least one of the parameters pstrName, xPos, yPos or area is invalid

Note that it is not necessary to call ReleaseObject on the returned handle once it is no longer needed. Ownership of the newly generated MTSMODEL is automatically transferred to the training set in which it has been generated.

◆ NewMTSModelW()

MTSMODEL NewMTSModelW	(	MTSIMAGE	handle,
		const wchar_t *	pstrName,
		double	xPos,
		double	yPos,
		TArea	area
	)

Creates a new pattern model.

A new model is defined as the combination of a model name, a pattern position inside and image and a feature window/extent relative to the pattern position.

Attention: Even though of double precision, xPos yPos should be integer numbers. Any fractional parts of the values passed in xPos or yPos will be rounded.

Parameters

[in]	handle	Handle to the MTSIMAGE from which the first instance of the new model is to be trained.
[in]	pstrName	Name of the new pattern model. Note that pattern do not have to be unique in Minos.
[in]	xPos	X coordinate of the first instance.
[in]	yPos	Y coordinate of the first instance.
[in]	area	Feature window extent for the new pattern model. The feature window is the smallest rectangle sufficient to recognize the pattern on the basis of its contents. It must be an axis-parallel rectangle with integer coordinates containing the point (0,0), and the left and top coordinates are therefore usually less than or equal to zero.

Returns

Handle to the newly generated model if model generation succeeded, nullptr otherwise. Typical error conditions are:

handle does not refer to a valid MTSIMAGE object
at least one of the parameters pstrName, xPos, yPos or area is invalid

Note that it is not necessary to call ReleaseObject on the returned handle once it is no longer needed. Ownership of the newly generated MTSMODEL is automatically transferred to the training set in which it has been generated.

◆ NumMTSClasses()

cvbval_t NumMTSClasses ( MTS handle )

Returns the number of distinguishable classes in a training set.

The number of distinguishable classes is the number of distinguishable names given to the MTSMODEL objects in a Minos training set. Therefore, there are at least 1 and a maximum of NumMTSModels distinguishable classes in a training set.

Note: Unlike with NumMTSModels or NumMTSInstances the concept of classes in a Minos training set is not based on a specific object type but on the analysis of the available MTSMODEL object collection.

Parameters

[in] handle Handle to the Minos training set to be queried.

Returns: Number of distinguishable classes in the training set referenced by handle, -1 if handle does not refer to a valid Minos training set.

See also: NumMTSModels

◆ NumMTSImageInstances()

cvbval_t NumMTSImageInstances ( MTSIMAGE handle )

Returns the number of instances marked in a MTSIMAGE.

Parameters

[in] handle Handle to the MTSIMAGE to be queried.

Returns: Number of instances marked in the MTSIMAGE referenced by handle or 0 if handle does not refer to a valid MTSIMAGE.

◆ NumMTSImages()

cvbval_t NumMTSImages ( MTS handle )

Returns the number of MTSIMAGE objects in a training set.

Attention: An object referred to by an MTSIMAGE handle is not an image like the ones referred to by an IMG handle! The MTSIMAGE is a container that combines an IMG with a list of the instances that have been marked in the image and a reference to owning training set. To retrieve the IMG from an MTSIMAGE use the function GetImageFromImage.

Parameters

[in] handle Handle to the Minos training set to be queried.

Returns: Number of MTSIMAGE objects in the training set referred to by handle or -1 if handle does not refer to a valid Minos training set.

See also: MTSIMAGE, IsMTSImage

◆ NumMTSInstances()

cvbval_t NumMTSInstances ( MTS handle )

Returns the number of MTSINSTANCE objects in a training set.

In other words, this function returns the total number of instances summed up over all MTSMODEL objects in a Minos training set.

Parameters

[in] handle Handle to the Minos training set to be queried.

Returns: Number of MTSINSTANCE objects in the training set referred to by handle or -1 if handle does not refer to a valid Minos training set.

See also: MTSINSTANCE, IsMTSInstance

◆ NumMTSModelInstances()

cvbval_t NumMTSModelInstances ( MTSMODEL handle )

Returns the number of instances representing a given pattern model.

... or, to put it differently, the number of instances that have been trained for a given model.

Parameters

[in] handle Handle to an MTSMODEL for which to query the number of trained instances.

Returns: Number of instances representing a given pattern model.

◆ NumMTSModels()

cvbval_t NumMTSModels ( MTS handle )

Returns the number of MTSMODEL objects in a training set.

In other words, this function returns the number of distinct models that have been trained into the training set. Note that different models with identical model name still count as distinct models.

Parameters

[in] handle Handle to the Minos training set to be queried.

Returns: Number of MTSMODEL objects in the training set referred to by handle or -1 if handle does not refer to a valid Minos training set.

See also: NumMTSClasses, MTSMODEL, IsMTSModel

◆ ReleaseMts()

cvbbool_t ReleaseMts ( MTS & handle )

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

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

Parameters

[in] handle Handle to the Minos training set to be released. If the reference classifier ceases to exist after the ReleaseMts call, the parameter handle will be overwritten with a nullptr, otherwise it will not be touched.

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

◆ RemoveMTSImage()

cvbbool_t RemoveMTSImage ( MTSIMAGE handle )

Removes an MTSIMAGE from a training set.

When removing an MTSIMAGE, all instances that have been marked on the image will be removed from the training set as well! Removing an image from a training set also means that the training set forfeits ownership of the image, i.e. RemoveMTSImage will automatically cause the MTSIMAGE to be disposed unless ShareObject has been used on it.

Parameters

[in] handle Handle to the MTSIMAGE to be removed.

Returns: TRUE if the image was removed successfully, FALSE if handle does not refer to a valid training set image.

◆ RemoveMTSInstance()

cvbbool_t RemoveMTSInstance ( MTSINSTANCE handle )

Removes an MTSINSTANCE from a training set.

Removing an instance from a training implies that the training set forfeits ownership of the instance, i.e. RemoveMTSInstance will automatically cause the MTSINSTANCE to be disposed unless ShareObject has been used on it.

If the removed instance was the last instance associated with a training set model, the empty model will not be removed from the training set!

Parameters

[in] handle Handle to the MTSINSTANCE to be removed.

Returns: TRUE if the image was removed successfully, FALSE if handle does not refer to a valid training set instance.

◆ RemoveMTSModel()

cvbbool_t RemoveMTSModel ( MTSMODEL handle )

Removes an MTSMODEL from a training set.

When removing an MTSMODEL, all instances that have been added to it will be removed from the training set as well! Removing a model from a training set also means that the training set forfeits ownership of the model, i.e. RemoveMTSModel will automatically cause the MTSMODEL to be disposed unless ShareObject has been used on it.

Parameters

[in] handle Handle to the MTSMODEL to be removed.

Returns: TRUE if the image was removed successfully, FALSE if handle does not refer to a valid training set model.

◆ SetFeatureWindow()

cvbbool_t SetFeatureWindow	(	MTSMODEL	handle,
		TArea	featureWindow
	)

Changes the feature window an MTSMODEL.

The feature window is the smallest rectangle sufficient to recognize the pattern on the basis of its contents. It must be an axis-parallel rectangle with integer coordinates containing the point (0,0), and the left and top coordinates are therefore usually less than or equal to zero.

Parameters

[in]	handle	Handle to the MTSMODEL for which to update the feature window.
[out]	featureWindow	Feature window to be set.

Returns: TRUE if the feature window was queried successfully, FALSE if handle does not refer to a valid MTSMODEL.

See also: GetFeatureWindow

◆ SetModelAdvance()

cvbbool_t SetModelAdvance	(	MTSMODEL	handle,
		double	dX,
		double	dY
	)

Returns the advance vector associated with a pattern model.

The advance vector may be used by Minos to speed up reading of contiguous strings. See the documentation of ReadToken for a detailed description of how Minos uses the advance vector during read operations and a code sample.

Parameters

[in]	handle	Handle to an MTSMODEL
[in]	dX	X component of the advance vector.
[in]	dY	Y component of the advance vector.

Returns: TRUE if the advance vector was queried successfully, FALSE if handle does not refer to a valid MTSMODEL object.

See also: GetModelAdvance, SetMTSGlobalAdvance, GetMTSGlobalAdvance

◆ SetModelName()

cvbbool_t SetModelName	(	MTSMODEL	handle,
		const char *	pstrName
	)

Changes the name of an MTSMODEL.

Parameters

[in]	handle	Handle to the MTSMODEL on which to set a new model name.
[in]	pstrName	New name to be set on the MTSMODEL (pointer to a zero-terminated string).

Returns: TRUE if the model name has been updated successfully, FALSE if handle does not refer to a valid MTSMODEL.

See also: GetModelName, GetModelNameW, SetModelNameW

◆ SetModelNameW()

cvbbool_t SetModelNameW	(	MTSMODEL	handle,
		const wchar_t *	pstrName
	)

Changes the name of an MTSMODEL.

Since: Common Vision Blox 13.00.000.

Parameters

[in]	handle	Handle to the MTSMODEL on which to set a new model name.
[in]	pstrName	New name to be set on the MTSMODEL (pointer to a zero-terminated string).

Returns: TRUE if the model name has been updated successfully, FALSE if handle does not refer to a valid MTSMODEL.

See also: GetModelName, GetModelNameW, SetModelNameW

◆ SetMTSComment()

cvbbool_t SetMTSComment	(	MTS	handle,
		const char *	pstrComment
	)

Sets the comment string on a Minos training set.

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

Parameters

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

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

See also: SetMTSCommentW, MTSComment, MTSCommentW

◆ SetMTSCommentW()

cvbbool_t SetMTSCommentW	(	MTS	handle,
		const wchar_t *	pstrComment
	)

Sets the comment string on a Minos training set.

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

Since: Common Vision Blox 13.00.000.

Parameters

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

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

See also: SetMTSCommentW, MTSComment, MTSCommentW

◆ SetMTSCorelParams()

cvbbool_t SetMTSCorelParams	(	MTS	handle,
		double	expRadius,
		double	corThresh
	)

Set the correlation parameters for Minos training.

The correlation parameters are the same as the ones that need to be passed to the function CreateMTS. They are mutable properties of the training set and will be evaluated and applied every time a new instance is added to the training set with NewMTSInstance or when TransformMTSImage is used.

Parameters

[in]	handle	Handle to the Minos training set.
[in]	expRadius	Expectation window radius. The expectation window radius defines a square area of width `expRadius * 2 + 1` centered around the location at which an instance is to be extracted: When trying to extract a new instance at the extraction position with NewMTSInstance (or indirectly via TransformMTSImage), Minos will use the function OptCorrelation on the expectation window to check if there is an alternative extraction position with a higher resemblance to the model available and if so, automatically use that alternative position for training. If you do not want to use this snap-in feature, simply set the expectation window radius to zero.
[in]	corThresh	Correlation threshold. When adding new instances either through NewMTSInstance or indirectly via TransformMTSImage) Minos will calculate the correlation (OptCorrelation) between the new instance location (which may have been altered by the snap-in feature; see description of `expRadius`) and the model image (as retrieved via GetImageFromModel). If the correlation is below the correlation threshold, Minos will generate a new model with the same name for the new instance (NewMTSInstance will show a message box before that to let the user confirm that the creation of a new model is ok).

Returns: TRUE if the correlation parameters have been set successfully, FALSE if handle does not refer to a valid Minos training set.

See also: GetMTSCorelParams, CreateMTS

◆ SetMTSGlobalAdvance()

cvbbool_t SetMTSGlobalAdvance	(	MTS	handle,
		cvbbool_t	useGlobalVector,
		double	globalX,
		double	globalY
	)

Set the global advance vectors for all the models in a training set.

In addition to the model-specific advance vectors a Minos training set also has a global advance vector that may be used to override the model-specific vectors. SetMTSGlobalAdvance can be used to switch between the two available options.

For a description of how the advance vectors are being used by Minos please refer to the description of ReadToken.

Parameters

[in]	handle	Handle to the Minos training set.
[in]	useGlobalVector	Flag specifying whether the global advance vector should be used (`TRUE`) or if Minos is to use the model-specific advance vectors (`FALSE`).
[in]	globalX	X component of the global advance vector to set.
[in]	globalY	Y component of the global advance vector to set.

Returns: TRUE if the new state has been applied successfully, FALSE if the handle does not refer to a valid Minos training set.

See also: GetMTSGlobalAdvance, GetModelAdvance, SetModelAdvance

◆ SetMTSModified()

cvbbool_t SetMTSModified	(	MTS	handle,
		cvbbool_t	isModified
	)

Sets a training set's internal modification flag.

A Minos training set has an internal state flag that indicates whether or not there are unsaved changes in the training set. This flag is set every time a MinosCVC.dll function has been used to modify the training set's contents and it is reset every time the training set has been successfully written to a file.

SetMTSModified may be used to set the flag to a selectable state.

Parameters

[in]	handle	Handle to a Minos training set.
[in]	isModified	State of the flag to be set.

Returns: TRUE if the flag has been set, FALSE if handle does not refer to a valid Minos training set.

See also: GetMTSModified

◆ ShareMts()

cvbbool_t ShareMts ( MTS handle )

Increments the reference count for a MTS 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 ShareMts must be countered with a call to ReleaseMts once the shared ownership ends (e.g. because the thread has terminated or the form has been destroyed) to prevent memory leaks.

Parameters

[in] handle Handle to the Minos training set to be shared.

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

◆ TransformMTSImage()

cvbbool_t TransformMTSImage	(	MTSIMAGE	handle,
		TMatrix	matrix
	)

Geometrically transforms an MTSIMAGE in the training set.

TransformMTSImage uses a 2x2 matrix to geometrically transform an existing MTSIMAGE. The resulting MTSIMAGE is automatically added to the training set that owns the original MTSIMAGE (GetMTSFromImage). The positions of all the MTSINSTANCE object from the original MTSIMAGE (NumMTSImageInstances, MTSImageInstance) are transformed as well and will also be added to the training set that owns the original MTSIMAGE.

On locations where the correlation test fails on the transformed instances (see CreateMTS, SetMTSCorelParams, GetMTSCorelParams) new models with the same pattern name and feature window as the original MTSINSTANCE will be created. To suppress the creation of new instances entirely, set the correlation threshold to 0.0 prior to calling TransformMTSImage (SetMTSCorelParams).

Parameters

[in]	handle	Handle to the MTSIMAGE to be transformed.
[in]	matrix	2x2 matrix to transform the image referenced by `handle` with.

Returns

TRUE if the input image was transformed and added successfully, FALSE otherwise. Typical error conditions are:

handle does not refer to a valid MTSIMAGE
an out of memory situation occurred

See also: CreateMTS, SetMTSCorelParams, GetMTSCorelParams

◆ TranslateModelOrigin()

cvbbool_t TranslateModelOrigin ( MTSMODEL handle )

Update the origin position (a.k.a. anchor point) of an MTSMODEL.

Calling this function will update the hot spot position of the MTSMODEL on which it is called from the model's image. In other words: To change the hot spot position of an MTSMODEL call GetImageFromModel, then modify the origin of the returned image's coordinate system and call TranslateModelOrigin to commit the change to the MTSMODEL.

Note that only the origin should be updated. The coordinate system matrix of the model image should always be the identity matrix.

Parameters

[in] handle Handle to a model on which to update the hot spot position.

Returns: TRUE if the position was updated successfully, FALSE otherwise.

Example: Shift the model origin of the first model by (+1, +1):

// assumptions:
// - mts points to a valid Minos training set in which at least one 
//   model with at least one instance has been trained.
auto mdl = MTSModel(mts, 0);
auto img = GetImageFromModel(mdl);
TCoordinateMap cs;
GetImageCoordinates(img, cs);
CS.OrgX += 1.0;
CS.OrgY += 1.0;
SetImageCoordinates(img, cs);
TranslateModelOrigin(mdl);

◆ WriteMTSFile()

cvbbool_t WriteMTSFile	(	MTS	handle,
		const char *	pstrFileName
	)

Stores a Minos training set to a file.

Note that since Common Vision Blox 13.00.000 WriteMTSFile will save the strings in the training set 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 WriteMTSFileEx - with that function the character encoding for the strings in the serialized training sets is selectable.

Parameters

[in]	handle	Handle to the Minos training set to be saved.
[in]	pstrFileName	Name of the file to which to save the Minos training set.

Returns: TRUE on success, FALSE if an error occurs.

See also: LoadMTSFile, LoadMTSFileW, WriteMTSFileW, WriteMTSFileEx, WriteCLFFileExW

◆ WriteMTSFileEx()

cvbbool_t WriteMTSFileEx	(	MTS	handle,
		const char *	pstrFileName,
		TMinosCharacterEncoding	encoding
	)

Saves a training set to a file with selectable character encoding.

As of Common Vision Blox 13.00.000 the functions WriteMTSFile and WriteMTSFileW will always save model names with UTF8 encoding and a prepended Byte Order Map in order to transparently support Unicode character sets. However, the prepended Byte Order Map might be annoying when using a MTS file saved with WriteMTSFile or WriteMTSFileW with older builds of Minos.

Therefore the functions WriteMTSFileEx and WriteMTSFileExW have been introduced: Both allow for the selection of the character encoding in the MTS file to either use the traditional code-page based 1-byte characters or the new UTF8 encoding.

Since: Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos training set.
[in]	pstrFileName	Zero terminated string with the file name to which to save the training set.
[in]	encoding	Value indicating the desired encoding method. See TMinosCharacterEncoding for the available options.

Returns: TRUE if the file was saves successfully, FALSE if saving failed.

See also: LoadMTSFile, LoadMTSFileW, WriteMTSFile, WriteMTSFileW, WriteMTSFileExW

◆ WriteMTSFileExW()

cvbbool_t WriteMTSFileExW	(	MTS	handle,
		const wchar_t *	pstrFileName,
		TMinosCharacterEncoding	encoding
	)

Saves a training set to a file with selectable character encoding.

As of Common Vision Blox 13.00.000 the functions WriteMTSFile and WriteMTSFileW will always save model names with UTF8 encoding and a prepended Byte Order Map in order to transparently support Unicode character sets. However, the prepended Byte Order Map might be annoying when using a MTS file saved with WriteMTSFile or WriteMTSFileW with older builds of Minos.

Therefore the functions WriteMTSFileEx and WriteMTSFileExW have been introduced: Both allow for the selection of the character encoding in the MTS file to either use the traditional code-page based 1-byte characters or the new UTF8 encoding.

Since: Common Vision Blox 13.00.000

Parameters

[in]	handle	Handle to the Minos training set.
[in]	pstrFileName	Zero terminated string with the file name to which to save the training set.
[in]	encoding	Value indicating the desired encoding method. See TMinosCharacterEncoding for the available options.

Returns: TRUE if the file was saves successfully, FALSE if saving failed.

See also: LoadMTSFile, LoadMTSFileW, WriteMTSFile, WriteMTSFileW, WriteMTSFileEx

◆ WriteMTSFileW()

cvbbool_t WriteMTSFileW	(	MTS	handle,
		const wchar_t *	pstrFileName
	)

Stores a Minos training set to a file.

Note that since Common Vision Blox 13.00.000 WriteMTSFile will save the strings in the training set 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 WriteMTSFileEx - with that function the character encoding for the strings in the serialized training sets is selectable.

Since: Common Vision Blox 13.00.000.

Parameters

[in]	handle	Handle to the Minos training set to be saved.
[in]	pstrFileName	Name of the file to which to save the Minos training set.

Returns: TRUE on success, FALSE if an error occurs.

See also: LoadMTSFile, LoadMTSFileW, WriteMTSFileW, WriteMTSFileEx, WriteCLFFileExW

Functions

Detailed Description

Function Documentation

◆ CreateImageFromInstance()

◆ CreateMTS()

◆ GetFeatureWindow()

◆ GetImageFromImage()

◆ GetImageFromInstance()

◆ GetImageFromModel()

◆ GetModelAdvance()

◆ GetModelFromInstance()

◆ GetModelName()

◆ GetModelNameW()

◆ GetMTSCorelParams()

◆ GetMTSExtent()

◆ GetMTSFromImage()

◆ GetMTSFromInstance()

◆ GetMTSFromModel()

◆ GetMTSGlobalAdvance()

◆ GetMTSLastFeatureWnd()

◆ GetMTSModified()

◆ GetMTSSize()

◆ InstanceIndex()

◆ InstanceX()

◆ InstanceY()

◆ IsMTS()

◆ IsMTSImage()

◆ IsMTSInstance()

◆ IsMTSModel()

◆ LearnCLFFromMTS()

◆ LearnCLFFromMTSW()

◆ LoadMTSFile()

◆ LoadMTSFileW()

◆ MemoryToMTS()

◆ MTSComment()

◆ MTSCommentW()

◆ MTSConsistencyCheck()

◆ MTSImage()

◆ MTSImageCheck()

◆ MTSImageIndex()

◆ MTSImageInstance()

◆ MTSInstance()

◆ MTSModel()

◆ MTSModelCheck()

◆ MTSModelImageCheck()

◆ MTSModelIndex()

◆ MTSModelInstance()

◆ MTSToMemory()

◆ MTSTransform()

◆ MTSVerifyToken()

◆ MTSVerifyTokenW()

◆ NewMTSImage()

◆ NewMTSImageIndex()

◆ NewMTSInstance()

◆ NewMTSInstanceW()

◆ NewMTSModel()

◆ NewMTSModelW()

◆ NumMTSClasses()

◆ NumMTSImageInstances()

◆ NumMTSImages()

◆ NumMTSInstances()

◆ NumMTSModelInstances()

◆ NumMTSModels()

◆ ReleaseMts()

◆ RemoveMTSImage()

◆ RemoveMTSInstance()

◆ RemoveMTSModel()

◆ SetFeatureWindow()

◆ SetModelAdvance()

◆ SetModelName()

◆ SetModelNameW()

◆ SetMTSComment()

◆ SetMTSCommentW()

◆ SetMTSCorelParams()

◆ SetMTSGlobalAdvance()

◆ SetMTSModified()

◆ ShareMts()

◆ TransformMTSImage()

◆ TranslateModelOrigin()

◆ WriteMTSFile()