Data Structures
struct	TFeatureMap
	Summarizes a number of parameters controlling feature extraction from images. More...

struct	TGeometrySpec
	Description of an example's geometry as used in the TGetLearningDataExampleGeometry callback. More...

struct	TInvarianceParams
	Controls the training of invariances for search classifiers. More...

struct	TProgress
	The TProgress structure controls the display of training progress using a user-definable pointer and three callback functions. More...

struct	TTrainParams
	Contains the main training parameters of classifiers and numerical predictors. More...

struct	TTrainSearchParams
	Controls the training of search classifiers. More...

Typedefs
typedef void(*	TGetLearningDataExampleClassLabel) (void pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, char szLabel, size_t &len)
	Give an example's class label. More...

typedef void(*	TGetLearningDataExampleClassLabelW) (void pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, wchar_t szLabel, size_t &len)
	Give an example's class label. More...

typedef cvbbool_t(*	TGetLearningDataExampleGeometry) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, TGeometrySpec &Specification)
	Give an example's geometry. More...

typedef cvbbool_t(*	TGetLearningDataExamplePosition) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, double &X, double &Y)
	Give an example's position. More...

typedef void(*	TGetLearningDataExampleVector) (void pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, double vector)
	Give the regression vector that goes with a learning example. More...

typedef void(*	TGetLearningDataFeatureWindow) (void *pPrivate, cvbdim_t &FWL, cvbdim_t &FWT, cvbdim_t &FWR, cvbdim_t &FWB)
	Retrieve the feature window of the training examples. More...

typedef IMG(*	TGetLearningDataImage) (void *pPrivate, cvbdim_t ImageIndex)
	Image retrieval. More...

typedef cvbval_t(*	TGetLearningDataNumExamplesInImage) (void *pPrivate, cvbval_t ImgIndex)
	Retrieve the number of examples in a given image. More...

typedef cvbdim_t(*	TGetLearningDataNumImagePlanes) (void *pPrivate)
	Function for retrieving the number of image planes. More...

typedef cvbval_t(*	TGetLearningDataNumImages) (void *pPrivate)
	Retrieve the number of images available. More...

typedef cvbdim_t(*	TGetLearningDataOutputDimension) (void *pPrivate)
	Give the output dimension in case of regression predictor training. More...

typedef void *	TLEARNINGDATAACCESS

typedef void(*	TLearningDataFinalRelease) (void *pPrivate)
	Learning data cleanup function. More...

typedef cvbbool_t(*	TProgressReport) (void *PPrivate, cvbval_t ID)
	Callback that is invoked every time a progress step has been made. More...

typedef void(*	TReleaseProgressReport) (void *PPrivate, cvbval_t ID)
	Callback that is invoked every time a progress phase has finished. More...

typedef void(*	TStartProgressReport) (void PPrivate, cvbval_t ID, const char Caption, cvbval_t Total)
	Callback that indicates the start of a new progress phase. More...

Enumerations
enum	TClassifierUsage { CU_Regression = 0x55550002 , CU_ClassifyOneVersusAll = 0x55550003 , CU_ClassifyOneVersusOne = 0x55550001 }
	Specifies the type of classification for which a classifier may be used. More...

enum	TGroupSpec { GS_XY , GS_XYScale , GS_XYAngle , GS_XYScaleAngle , GS_XYMatrix }
	Defines the geometry description mode for the TGeometrySpec structure. More...

enum	TInvarianceType { TI_Translations = 1 , TI_RotScaleTrans = 2 , TI_AffineGroup = 3 }
	Invariance generation that may be used during search classifier training. More...

enum	TMapMode { MM_MantoStandard = 0 }
	Feature map mode used in Polimago Classifiers. More...

enum	TPolimagoTrainingError { PMERR_OK = 0 , PMERR_BadAccessForSearchTraining = -1 , PMERR_ImageDimensionMismatch = -2 , PMERR_InconsistentFeaturemap = -4 , PMERR_BadInvarianceType = -5 , PMERR_AccessVsUsageMismatch = -6 , PMERR_RegressionError = -7 , PMERR_CreateClfError = -8 , PMERR_HoldoutTooSmall = -9 , PMERR_HoldoutTooLarge = -10 , PMERR_PreprocessingError = -11 , PMERR_ClassNotInClassifier = -12 , PMERR_BadAccess = -13 , PMERR_GeneralError = -50 }
	Return codes used by the training functions of Polimago (PMTrainClassifierFromMts, PMTrainClassifierFromSil, PMTrainSearchClassifierFromMts, PMTrainSearchClassifierFromSil) to indicate what went wrong during training. More...

Functions
TLEARNINGDATAACCESS	PMCreateLearningDataAccess (void *pPrivate, TGetLearningDataNumImagePlanes getNumImagePlanes, TGetLearningDataImage getImageFromImageIndex, TGetLearningDataNumImages getNumImages, TGetLearningDataNumExamplesInImage getNumExamplesInImage, TGetLearningDataExamplePosition getExamplePosition, TGetLearningDataExampleClassLabel getClassLabel, TGetLearningDataOutputDimension getOutputDimension, TGetLearningDataExampleVector getExampleVector, TGetLearningDataFeatureWindow getFeatureWindow, TLearningDataFinalRelease finalRelease)
	Generate a generic data access object for search classifier learning. More...

TLEARNINGDATAACCESS	PMCreateLearningDataAccessSearch (void *pPrivate, TGetLearningDataNumImagePlanes getNumImagePlanes, TGetLearningDataImage getImageFromImageIndex, TGetLearningDataNumImages getNumImages, TGetLearningDataNumExamplesInImage getNumExamplesInImage, TGetLearningDataExampleGeometry getExampleGeometry, TGetLearningDataFeatureWindow getFeatureWindow, TLearningDataFinalRelease finalRelease)
	Generate a generic data access object for search classifier learning. More...

TLEARNINGDATAACCESS	PMCreateLearningDataAccessW (void *pPrivate, TGetLearningDataNumImagePlanes getNumImagePlanes, TGetLearningDataImage getImageFromImageIndex, TGetLearningDataNumImages getNumImages, TGetLearningDataNumExamplesInImage getNumExamplesInImage, TGetLearningDataExamplePosition getExamplePosition, TGetLearningDataExampleClassLabelW getClassLabel, TGetLearningDataOutputDimension getOutputDimension, TGetLearningDataExampleVector getExampleVector, TGetLearningDataFeatureWindow getFeatureWindow, TLearningDataFinalRelease finalRelease)
	Generate a generic data access object for search classifier learning. More...

cvbbool_t	PMExtractFeatureImage (IMG source, TFeatureMap featureMap, double X, double Y, TMatrix M, IMG &imgOut)
	Extract a training sample image with definable Geometry. More...

cvbbool_t	PMGetErrormessage (TPolimagoTrainingError errorCode, char *szBuffer, size_t &len)
	The function returns a string interpreting an error code that has been returned by one of the Polimago training functions (PMTrainClassifierFromMts, PMTrainClassifierFromSil, PMTrainSearchClassifierFromMts, PMTrainSearchClassifierFromSil). More...

TPolimagoTrainingError	PMTrainClassifierFromMts (MTS mts, TProgress Progress, TClassifierUsage usage, const char szPreproCode, cvbval_t featureResolution, double lambda, cvbbool_t interpolate, TCLF &Clf)
	The function creates a classifier from a given MTS (Minos Training Set). More...

TPolimagoTrainingError	PMTrainClassifierFromSil (TSIL sil, TProgress Progress, TClassifierUsage usage, const char szPreproCode, cvbval_t featureResolution, double lambda, cvbbool_t interpolate, TCLF &Clf)
	The function creates a classifier from a given SIL (Sample Image List). More...

TPolimagoTrainingError	PMTrainClassifierGeneric (TLEARNINGDATAACCESS db, TProgress Progress, TClassifierUsage usage, const char szPreproCode, cvbval_t featureResolution, double lambda, cvbbool_t interpolate, TCLF &Clf)
	Generate a classification or regression predictor from a generic database access object. More...

TPolimagoTrainingError	PMTrainSearchClassifierFromMts (MTS mts, TProgress Progress, const char szPreproCode, double lambda, TTrainSearchParams trainSearchParams, TSCLF &searchClf)
	The function attempts to create a search classifier from the specified Minos Training Set. More...

TPolimagoTrainingError	PMTrainSearchClassifierFromSil (TSIL sil, TProgress Progress, const char szPreproCode, double lambda, TTrainSearchParams trainSearchParams, TSCLF &searchClf)
	The function attempts to create a search classifier from the specified SIL (Sample Image List). More...

TPolimagoTrainingError	PMTrainSearchClassifierGeneric (TLEARNINGDATAACCESS db, TProgress Progress, const char szPreproCode, double lambda, TTrainSearchParams trainSearchParams, TSCLF &searchClf)
	Generate a search classifier from a generic database access object. More...

Detailed Description

Typedef Documentation

◆ TGetLearningDataExampleClassLabel

typedef void(* TGetLearningDataExampleClassLabel) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, char *szLabel, size_t &len)

Give an example's class label.

Polimago will call this function when it needs to retrieve an example's class label. This method is therefore only required for generating and/or testing classification predictors.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImageIndex	Index of the image in which the example is located.
[in]	ExampleIndex	Index of the example for which to determine the label.
[in]	szLabel	Pointer to the buffer into which the string may be copied. Please make sure to include zero termination of that buffer.
[in,out]	len	Size of the buffer pointed to by `szLabel`. Will should be set to the actual number of characters copied into that buffer.

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

◆ TGetLearningDataExampleClassLabelW

typedef void(* TGetLearningDataExampleClassLabelW) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, wchar_t *szLabel, size_t &len)

Give an example's class label.

Polimago will call this function when it needs to retrieve an example's class label. This method is therefore only required for generating and/or testing classification predictors.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImageIndex	Index of the image in which the example is located.
[in]	ExampleIndex	Index of the example for which to determine the label.
[in]	szLabel	Pointer to the buffer into which the string may be copied. Please make sure to include zero termination of that buffer. If you are going to use Unicode characters, make sure to convert them to UTF8 encoding where necessary
[in,out]	len	Size of the buffer pointed to by `szLabel`. Will should be set to the actual number of characters copied into that buffer.

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

◆ TGetLearningDataExampleGeometry

typedef cvbbool_t(* TGetLearningDataExampleGeometry) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, TGeometrySpec &Specification)

Give an example's geometry.

Polimago will call this function when it needs to retrieve an example's geometry. This method is only required for generating search predictors.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImageIndex	Index of the image in which the example is located.
[in]	ExampleIndex	Index of the example for which to determine the geometrical situation.
[out]	Specification	Specification of the example's current geometrical situation.

Returns: TRUE if the geometry was determined successfully, FALSE otherwise.

◆ TGetLearningDataExamplePosition

typedef cvbbool_t(* TGetLearningDataExamplePosition) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, double &X, double &Y)

Give an example's position.

Polimago will call this function when it needs to retrieve an example's position.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImageIndex	Index of the image in which the example is located.
[in]	ExampleIndex	Index of the example for which to determine the geometrical situation.
[out]	X	x-coordinate at which the example is located.
[out]	Y	x-coordinate at which the example is located.

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

◆ TGetLearningDataExampleVector

typedef void(* TGetLearningDataExampleVector) (void *pPrivate, cvbval_t ImageIndex, cvbval_t ExampleIndex, double *vector)

Give the regression vector that goes with a learning example.

Polimago will call this function when it needs to determine the regression vector label that goes with the specified example.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImageIndex	Index of the image in which the example is located.
[in]	ExampleIndex	Index of the example for which Polimago wants to know the regression vector.
[in]	vector	Pointer to the buffer where the regression vector is to be stored. The buffer may be assumed to be big enough to receive a number of `double` values equal to the value returned by the callback function TGetLearningDataOutputDimension.

◆ TGetLearningDataFeatureWindow

typedef void(* TGetLearningDataFeatureWindow) (void *pPrivate, cvbdim_t &FWL, cvbdim_t &FWT, cvbdim_t &FWR, cvbdim_t &FWB)

Retrieve the feature window of the training examples.

Polimago will call this function to determine the size of the feature window of the examples to be trained (reminder: All examples need to fit into the same feature window).

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[out]	FWL	Left edge of the feature window (should be zero or less than zero).
[out]	FWT	Top edge of the feature window (should be zero or less than zero).
[out]	FWR	Right edge of the feature window (should be zero or greater than zero).
[out]	FWB	Bottom edge of the feature window (should be zero or greater than zero).

◆ TGetLearningDataImage

typedef IMG(* TGetLearningDataImage) (void *pPrivate, cvbdim_t ImageIndex)

Image retrieval.

Return the image referred to by the ImageIndex parameter.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImageIndex	Index of the image to be returned.

Returns: Image referred to by the ImageIndex parameter.

◆ TGetLearningDataNumExamplesInImage

typedef cvbval_t(* TGetLearningDataNumExamplesInImage) (void *pPrivate, cvbval_t ImgIndex)

Retrieve the number of examples in a given image.

Polimago will call this method to query the number of examples available in a given image.

Parameters

[in]	pPrivate	Pointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]	ImgIndex	Index of the image for which to query the information.

Returns: Number of examples available in the image referred to by the ImgIndex parameter.

◆ TGetLearningDataNumImagePlanes

typedef cvbdim_t(* TGetLearningDataNumImagePlanes) (void *pPrivate)

Function for retrieving the number of image planes.

Queries the number of image planes the training material has. The return value must be the same as long as the TLEARNINGDATAACCESS object lives.

Parameters

[in] pPrivate Pointer to the internally used data (see description of PMCreateLearningDataAccess).

Returns: Number of image planes (must be either 1 or 3).

◆ TGetLearningDataNumImages

typedef cvbval_t(* TGetLearningDataNumImages) (void *pPrivate)

Retrieve the number of images available.

Polimago will call this method to query the number of images available in a learning data access object.

Parameters

[in] pPrivate Pointer to the internally used data (see description of PMCreateLearningDataAccess).

Returns: Number of images available.

◆ TGetLearningDataOutputDimension

typedef cvbdim_t(* TGetLearningDataOutputDimension) (void *pPrivate)

Give the output dimension in case of regression predictor training.

Polimago will call this function when it needs to determine the number of output dimensions a regression predictor should generate.

Parameters

[in] pPrivate Pointer to the internally used data (see description of PMCreateLearningDataAccess).

Returns: Output dimension of the predictor (which is identical with the dimension of the vectors provided by TGetLearningDataExampleVector).

◆ TLEARNINGDATAACCESS

typedef void* TLEARNINGDATAACCESS

Handle to a generic learning data access structure.

◆ TLearningDataFinalRelease

typedef void(* TLearningDataFinalRelease) (void *pPrivate)

Learning data cleanup function.

Polimago will invoke this function once the final release call has been executed on the TLEARNINGDATAACCESS structure returned initially by PMCreateLearningDataAccess. In this function the implementer should release any resources (memory, files, etc.) associated with the learning data set to prevent memory leaks.

◆ TProgressReport

typedef cvbbool_t(* TProgressReport) (void *PPrivate, cvbval_t ID)

Callback that is invoked every time a progress step has been made.

Parameters

[in]	PPrivate	Pointer to user definable data as given in the TProgress structure.
[in]	ID	Number identifying the progress phase.

Returns: Return TRUE to continue operation, FALSE if you want to the current operation interrupt.

◆ TReleaseProgressReport

typedef void(* TReleaseProgressReport) (void *PPrivate, cvbval_t ID)

Callback that is invoked every time a progress phase has finished.

Parameters

[in]	PPrivate	Pointer to user definable data as given in the TProgress structure.
[in]	ID	Number identifying the progress phase.

◆ TStartProgressReport

typedef void(* TStartProgressReport) (void *PPrivate, cvbval_t ID, const char *Caption, cvbval_t Total)

Callback that indicates the start of a new progress phase.

Parameters

[in]	PPrivate	Pointer to user definable data as given in the TProgress structure.
[in]	ID	Number identifying a progress phase.
[in]	Caption	Printable name of the progress phase that is being started.
[in]	Total	Total number of steps of which the new progress phase consists.

Enumeration Type Documentation

◆ TClassifierUsage

enum TClassifierUsage

Specifies the type of classification for which a classifier may be used.

Enumerator
CU_Regression	Use for estimation of vector-valued functions (PMPredictVector). The dimension of the output is determined by the training set. This usage type is enforced for the search functions of Polimago.
CU_ClassifyOneVersusAll	Use for classification (PMClassify). Estimates a vector-valued function with as many components as the number of classes. The index of the maximal component is the predicted class.
CU_ClassifyOneVersusOne	Used as default for classification (PMClassify). Estimates a vector- valued function with as many components as there are pairs of classes. The pair classifiers then each cast a vote for the winner in the pair and the class with the largest total number of votes is the predicted class. This is similar to the so-called voting mode available in Common Vision Blox Manto.

◆ TGroupSpec

enum TGroupSpec

Defines the geometry description mode for the TGeometrySpec structure.

Enumerator
GS_XY	Geometry is described by just two double precision values corresponding to the x and y position of the example.
GS_XYScale	Geometry is described by three double precision values corresponding to the x and y position plus the scale.
GS_XYAngle	Geometry is described by three double precision values corresponding to the x and y position plus the rotation.
GS_XYScaleAngle	Geometry is described by four double precision values corresponding to the x and y position plus the scale and rotation.
GS_XYMatrix	Geometry is described by six double precision values corresponding to the x and y position and a 2x2 matrix.

◆ TInvarianceType

enum TInvarianceType

Invariance generation that may be used during search classifier training.

Enumerator
TI_Translations	Translated object only (positional invariance).
TI_RotScaleTrans	Translated, rotated and scaled objects.
TI_AffineGroup	Translated and affine transformed object (position plus 2x2 matrix).

◆ TMapMode

enum TMapMode

Feature map mode used in Polimago Classifiers.

Enumerator
MM_MantoStandard	Currently the only available map mode.

◆ TPolimagoTrainingError

enum TPolimagoTrainingError

Return codes used by the training functions of Polimago (PMTrainClassifierFromMts, PMTrainClassifierFromSil, PMTrainSearchClassifierFromMts, PMTrainSearchClassifierFromSil) to indicate what went wrong during training.

Enumerator
PMERR_OK	Training finished successfully.
PMERR_BadAccessForSearchTraining	Training misses required callback definitions (only used internally).
PMERR_ImageDimensionMismatch	TFeatureMap and callbacks provide contradicting information about the number of images planes (only used internally).
PMERR_InconsistentFeaturemap	With the given parameters, feature window width and height must be multiples of the preprocessing code's granularity.
PMERR_BadInvarianceType	An invalid variance types was specified.
PMERR_AccessVsUsageMismatch	The image data access definition is insufficient for the specified classifier usage.
PMERR_RegressionError	An error occurred while calculating the ridge regression during classifier generation.
PMERR_CreateClfError	Polimago was unable to create a classifier (potentially due to an out of memory situation).
PMERR_HoldoutTooSmall	The holdout size was smaller or equal to 1.
PMERR_HoldoutTooLarge	The holdout size was bigger or equal to the lest represented class's sample count.
PMERR_PreprocessingError	Feature extraction failed.
PMERR_ClassNotInClassifier	Classifier does not contain a given class.
PMERR_BadAccess	Image access definition was insufficient (only used internally).
PMERR_GeneralError	Unspecified error occurred.

Function Documentation

◆ PMCreateLearningDataAccess()

TLEARNINGDATAACCESS PMCreateLearningDataAccess	(	void *	pPrivate,
		TGetLearningDataNumImagePlanes	getNumImagePlanes,
		TGetLearningDataImage	getImageFromImageIndex,
		TGetLearningDataNumImages	getNumImages,
		TGetLearningDataNumExamplesInImage	getNumExamplesInImage,
		TGetLearningDataExamplePosition	getExamplePosition,
		TGetLearningDataExampleClassLabel	getClassLabel,
		TGetLearningDataOutputDimension	getOutputDimension,
		TGetLearningDataExampleVector	getExampleVector,
		TGetLearningDataFeatureWindow	getFeatureWindow,
		TLearningDataFinalRelease	finalRelease
	)

Generate a generic data access object for search classifier learning.

This function creates an initializes an object for generic database access that can be used to train classification and regression classifiers using the function PMTrainClassifierGeneric. This object is basically the combination of a private data pointer (that may be used for accessing whatever underlying resources may be used for classifier training) and callbacks that Polimago will invoke to retrieve the information it needs about the training data set.

Attention: The data access object is a reference counted object. Once it is no longer needed it should be disposed by calling the function ReleaseObject from the CVCImg.dll on it. Once the object is removed from memory, the callback provided in the finalRelease parameter will be called to notify you of the destruction of the object - at this point (and only at this point) it will be safe to release whatever resources were in use for classifier training.

Parameters

[in]	pPrivate	Private data pointer for use with the learning data access object.
[in]	getNumImagePlanes	Callback that specifies the number of image planes Polimago should use for training. Must not be `NULL`.
[in]	getImageFromImageIndex	Callback that allows Polimago to retrieve specific training images. Must not be `NULL`.
[in]	getNumImages	Callback with which Polimago queries the total number of images available for training. Must not be `NULL`.
[in]	getNumExamplesInImage	Callback with which Polimago determines how many examples are present in a given image. Must not be `NULL`.
[in]	getExamplePosition	Callback Polimago uses to determine the position of an example. Must not be `NULL`.
[in]	getClassLabel	Callback that Polimago uses to query the (string literal) label for a given example. May be `NULL`, in which case the resulting TLEARNINGDATAACCESS object may not be used for generating classification predictors.
[in]	getOutputDimension	Callback that Polimago uses to query the regression dimension to be used when generating a regression predictor. May be `NULL`, in which case the resulting TLEARNINGDATAACCESS object may not be used for generating regression predictors.
[in]	getFeatureWindow	Callback with which Polimago determines the feature window to used for training. Must not be `NULL`.
[in]	finalRelease	Callback to be invoked when the object created by this function call is removed from memory. May be used to free any resources that might have been in use by this object. May be `NULL` if there is no per-object cleanup necessary.
[in]	getExampleVector	Callback that Polimago uses to query the a sample's vector (when doing regression training).

Returns: Newly created learning data access object or NULL if an error occurred (which can only happen if one of the mandatory callbacks has been set to NULL).

◆ PMCreateLearningDataAccessSearch()

TLEARNINGDATAACCESS PMCreateLearningDataAccessSearch	(	void *	pPrivate,
		TGetLearningDataNumImagePlanes	getNumImagePlanes,
		TGetLearningDataImage	getImageFromImageIndex,
		TGetLearningDataNumImages	getNumImages,
		TGetLearningDataNumExamplesInImage	getNumExamplesInImage,
		TGetLearningDataExampleGeometry	getExampleGeometry,
		TGetLearningDataFeatureWindow	getFeatureWindow,
		TLearningDataFinalRelease	finalRelease
	)

Generate a generic data access object for search classifier learning.

This function creates an initializes an object for generic database access that can be used to train search classifiers using the function PMTrainSearchClassifierGeneric. This object is basically the combination of a private data pointer (that may be used for accessing whatever underlying resources may be used for classifier training) and callbacks that Polimago will invoke to retrieve the information it needs about the training data set.

Attention: The data access object is a reference counted object. Once it is no longer needed it should be disposed by calling the function ReleaseObject from the CVCImg.dll on it. Once the object is removed from memory, the callback provided in the finalRelease parameter will be called to notify you of the destruction of the object - at this point (and only at this point) it will be safe to release whatever resources were in use for classifier training.

Parameters

[in]	pPrivate	Private data pointer for use with the learning data access object.
[in]	getNumImagePlanes	Callback that specifies the number of image planes Polimago should use for training. Must not be `NULL`.
[in]	getImageFromImageIndex	Callback that allows Polimago to retrieve specific training images. Must not be `NULL`.
[in]	getNumImages	Callback with which Polimago queries the total number of images available for training. Must not be `NULL`.
[in]	getNumExamplesInImage	Callback with which Polimago determines how many examples are present in a given image. Must not be `NULL`.
[in]	getExampleGeometry	Callback Polimago uses to determine the position and 2D pose of an example. Must not be `NULL`.
[in]	getFeatureWindow	Callback with which Polimago determines the feature window to used for training. Must not be `NULL`.
[in]	finalRelease	Callback to be invoked when the object created by this function call is removed from memory. May be used to free any resources that might have been in use by this object. May be `NULL` if there is no per-object cleanup necessary.

Returns: Newly created learning data access object or NULL if an error occurred (which can only happen if one of the callbacks has been set to NULL).

◆ PMCreateLearningDataAccessW()

TLEARNINGDATAACCESS PMCreateLearningDataAccessW	(	void *	pPrivate,
		TGetLearningDataNumImagePlanes	getNumImagePlanes,
		TGetLearningDataImage	getImageFromImageIndex,
		TGetLearningDataNumImages	getNumImages,
		TGetLearningDataNumExamplesInImage	getNumExamplesInImage,
		TGetLearningDataExamplePosition	getExamplePosition,
		TGetLearningDataExampleClassLabelW	getClassLabel,
		TGetLearningDataOutputDimension	getOutputDimension,
		TGetLearningDataExampleVector	getExampleVector,
		TGetLearningDataFeatureWindow	getFeatureWindow,
		TLearningDataFinalRelease	finalRelease
	)

Generate a generic data access object for search classifier learning.

This function creates an initializes an object for generic database access that can be used to train classification and regression classifiers using the function PMTrainClassifierGeneric. This object is basically the combination of a private data pointer (that may be used for accessing whatever underlying resources may be used for classifier training) and callbacks that Polimago will invoke to retrieve the information it needs about the training data set.

Attention: The data access object is a reference counted object. Once it is no longer needed it should be disposed by calling the function ReleaseObject from the CVCImg.dll on it. Once the object is removed from memory, the callback provided in the finalRelease parameter will be called to notify you of the destruction of the object - at this point (and only at this point) it will be safe to release whatever resources were in use for classifier training.

Parameters

[in]	pPrivate	Private data pointer for use with the learning data access object.
[in]	getNumImagePlanes	Callback that specifies the number of image planes Polimago should use for training. Must not be `NULL`.
[in]	getImageFromImageIndex	Callback that allows Polimago to retrieve specific training images. Must not be `NULL`.
[in]	getNumImages	Callback with which Polimago queries the total number of images available for training. Must not be `NULL`.
[in]	getNumExamplesInImage	Callback with which Polimago determines how many examples are present in a given image. Must not be `NULL`.
[in]	getExamplePosition	Callback Polimago uses to determine the position of an example. Must not be `NULL`.
[in]	getClassLabel	Callback that Polimago uses to query the (string literal) label for a given example. May be `NULL`, in which case the resulting TLEARNINGDATAACCESS object may not be used for generating classification predictors.
[in]	getOutputDimension	Callback that Polimago uses to query the regression dimension to be used when generating a regression predictor. May be `NULL`, in which case the resulting TLEARNINGDATAACCESS object may not be used for generating regression predictors.
[in]	getFeatureWindow	Callback with which Polimago determines the feature window to used for training. Must not be `NULL`.
[in]	finalRelease	Callback to be invoked when the object created by this function call is removed from memory. May be used to free any resources that might have been in use by this object. May be `NULL` if there is no per-object cleanup necessary.
[in]	getExampleVector	Callback with which Polimago determined the vector-valued label to be associated with an example. May be `NULL`, in which case the resulting TLEARNINGDATAACCESS object may not be used for generating regression predictors.

Returns: Newly created learning data access object or NULL if an error occurred (which can only happen if one of the mandatory callbacks has been set to NULL).

◆ PMExtractFeatureImage()

cvbbool_t PMExtractFeatureImage	(	IMG	source,
		TFeatureMap	featureMap,
		double	X,
		double	Y,
		TMatrix	M,
		IMG &	imgOut
	)

Extract a training sample image with definable Geometry.

This method extracts from the source image a sample as defined by the featureMap, X, Y and M parameter. This effectively simulates what happens during search classifier training.

Parameters

[in]	source	Image to extract from.
[in]	featureMap	Training sample definition to use.
[in]	X	Position at which to extract.
[in]	Y	Position at which to extract.
[in]	M	Transformation to apply during extraction.
[out]	imgOut	image.

Returns: TRUE if sample image extraction succeeded, FALSE otherwise.

◆ PMGetErrormessage()

cvbbool_t PMGetErrormessage	(	TPolimagoTrainingError	errorCode,
		char *	szBuffer,
		size_t &	len
	)

The function returns a string interpreting an error code that has been returned by one of the Polimago training functions (PMTrainClassifierFromMts, PMTrainClassifierFromSil, PMTrainSearchClassifierFromMts, PMTrainSearchClassifierFromSil).

Converts an error value returned by one of the classifier training functions into a printable text message (English).

Parameters

[in]	errorCode	Numerical error code returned by the classifier training functions (see TPolimagoTrainingError).
[in]	szBuffer	Destination buffer into which to copy the error message. Pass `NULL` here to retrieve the required buffer lenght in the `len` parameter without actually copying the error message.
[in]	len	Length (in bytes) of the buffer pointed to by `szBuffer`. If the error message length plus terminating zero exceeds the buffer size, the error message will be truncated to len-1 bytes, `FALSE` will be returned to indicate the insufficient buffer.

Returns: TRUE if the error message was copied successfully, FALSE if the input buffer is NULL or the buffer size is too small to receive the whole error message.

◆ PMTrainClassifierFromMts()

TPolimagoTrainingError PMTrainClassifierFromMts	(	MTS	mts,
		TProgress *	Progress,
		TClassifierUsage	usage,
		const char *	szPreproCode,
		cvbval_t	featureResolution,
		double	lambda,
		cvbbool_t	interpolate,
		TCLF &	Clf
	)

The function creates a classifier from a given MTS (Minos Training Set).

Generate a classifier for classification or regression usage form the given sample image list. Generally speaking the SIL objects are the training database of choice for classification and regression classifiers, but under certain conditions (feature window identical for all classes) valid classification classifiers may also be generated from an MTS file.

Attention: Note that it is not possible to generate a regression classifier from a Minos Training Set.

Parameters

[in]	mts	Specifies the training data set - in this case a sample image list.
[in]	Progress	Progress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]	usage	Classifier usage - regression, 1v1 or 1vall classification (see description of TClassifierUsage). Note that CU_Regression is not permitted here.
[in]	szPreproCode	Preprocessing to be used for training code.
[in]	featureResolution	Determines the dimensions of the classifier's retina (see feature-map lesson in the tutorial on search functions). Remember that the length of the preprocessing code should not exceed the feature resolution (otherwise the error PMERR_InconsistentFeaturemap will be returned).
[in]	lambda	Ridge regression regularization constant. The default value 0.01 works well in most cases. May be slightly increased for very small numbers of training examples and slightly decreased for very large numbers of training examples.
[in]	interpolate	Image interpolation mode for feature extraction. `implies` simple truncation of fractional coordinates, `TRUE` (recommended) implies bilinear interpolation.
[out]	Clf	Receives the handle of the generated classifier.

Returns: One of the return codes defined in TPolimagoTrainingError.

◆ PMTrainClassifierFromSil()

TPolimagoTrainingError PMTrainClassifierFromSil	(	TSIL	sil,
		TProgress *	Progress,
		TClassifierUsage	usage,
		const char *	szPreproCode,
		cvbval_t	featureResolution,
		double	lambda,
		cvbbool_t	interpolate,
		TCLF &	Clf
	)

The function creates a classifier from a given SIL (Sample Image List).

Generate a classifier for classification or regression usage form the given sample image list.

Parameters

[in]	sil	Specifies the training data set - in this case a sample image list.
[in]	Progress	Progress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]	usage	Classifier usage - regression, 1v1 or 1vall classification (see description of TClassifierUsage). Note that the SIL's label type should be compatible with the parameter given here. If it is not, the SIL labels will converted if possible, but the result may prove to be useless.
[in]	szPreproCode	Preprocessing to be used for training code.
[in]	featureResolution	Determines the dimensions of the classifier's retina (see feature-map lesson in the tutorial on search functions). Remember that the length of the preprocessing code should not exceed the feature resolution (otherwise the error PMERR_InconsistentFeaturemap will be returned).
[in]	lambda	Ridge regression regularization constant. The default value 0.01 works well in most cases. May be slightly increased for very small numbers of training examples and slightly decreased for very large numbers of training examples.
[in]	interpolate	Image interpolation mode for feature extraction. `implies` simple truncation of fractional coordinates, `TRUE` (recommended) implies bilinear interpolation.
[out]	Clf	Receives the handle of the generated classifier.

Returns: One of the return codes defined in TPolimagoTrainingError.

◆ PMTrainClassifierGeneric()

TPolimagoTrainingError PMTrainClassifierGeneric	(	TLEARNINGDATAACCESS	db,
		TProgress *	Progress,
		TClassifierUsage	usage,
		const char *	szPreproCode,
		cvbval_t	featureResolution,
		double	lambda,
		cvbbool_t	interpolate,
		TCLF &	Clf
	)

Generate a classification or regression predictor from a generic database access object.

Generate the access object using the function PMCreateLearningDataAccess, specifying the callback routines that implement the database access. Note that depending on the usage mode the TGetLearningDataExampleClassLabel (CU_ClassifyOneVersusAll, CU_ClassifyOneVersusOne) or the TGetLearningDataOutputDimension and TGetLearningDataExampleVector callbacks (CU_Regression) must not be NULL, otherwise a PMERR_AccessVsUsageMismatch error will be returned.

Attention: The classifier object generated by this function must be cleared from memory with a ReleaseObject call (CVCImg.dll) once it is no longer needed.

Parameters

[in]	db	Specifies the training data set.
[in]	Progress	Progress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]	usage	Classifier usage - regression, 1v1 or 1vall classification (see description of TClassifierUsage). Note that the SIL's label type should be compatible with the parameter given here. If it is not, the SIL labels will converted if possible, but the result may prove to be useless.
[in]	szPreproCode	Preprocessing to be used for training code.
[in]	featureResolution	Determines the dimensions of the classifier's retina (see feature-map lesson in the tutorial on search functions). Remember that the length of the preprocessing code should not exceed the feature resolution (otherwise the error PMERR_InconsistentFeaturemap will be returned).
[in]	lambda	Ridge regression regularization constant. The default value 0.01 works well in most cases. May be slightly increased for very small numbers of training examples and slightly decreased for very large numbers of training examples.
[in]	interpolate	Image interpolation mode for feature extraction. `implies` simple truncation of fractional coordinates, `TRUE` (recommended) implies bilinear interpolation.
[out]	Clf	Receives the handle of the generated classifier.

Returns: One of the return codes defined in TPolimagoTrainingError.

◆ PMTrainSearchClassifierFromMts()

TPolimagoTrainingError PMTrainSearchClassifierFromMts	(	MTS	mts,
		TProgress *	Progress,
		const char *	szPreproCode,
		double	lambda,
		TTrainSearchParams	trainSearchParams,
		TSCLF &	searchClf
	)

The function attempts to create a search classifier from the specified Minos Training Set.

For additional information please see the tutorial on search functions of Polimago.

Parameters

[in]	mts	Training data set.
[in]	Progress	Progress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]	szPreproCode	Preprocessing to be used for training.
[in]	lambda	Ridge regression regularization constant. The default value 0.01 works well in most cases. May be slightly increased for very small numbers of training examples and slightly decreased for very large numbers of training examples.
[in]	trainSearchParams	Parameters for search training (see description of TTrainSearchParams struct).
[out]	searchClf	Receives the handle of the generated classifier.

Returns: One of the return codes defined in TPolimagoTrainingError.

◆ PMTrainSearchClassifierFromSil()

TPolimagoTrainingError PMTrainSearchClassifierFromSil	(	TSIL	sil,
		TProgress *	Progress,
		const char *	szPreproCode,
		double	lambda,
		TTrainSearchParams	trainSearchParams,
		TSCLF &	searchClf
	)

The function attempts to create a search classifier from the specified SIL (Sample Image List).

For additional information please see the tutorial on search functions of Polimago.

Attention

Note that generating a search classifier from a sample image list is not always possible - at least not with satisfactory results. In order to be suitable for search classifier generation, a sample image list should

Contain only one class (exclusion status will be ignored!)
Contain sample images with a sufficiently large fringe around them so that search classifier generation has enough leeway to extract samples for offset/rotation/scale correction.

Note that generating a search classifier from a sample image list will alter the list's feature window parameters based on the contents of the TTrainSearchParams argument's invariance parameters to make sure that the feature window is compatible with the invariance parameters!

Parameters

[in]	sil	Training data set.
[in]	Progress	Progress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]	szPreproCode	Preprocessing to be used for training.
[in]	lambda	Ridge regression regularization constant. The default value 0.01 works well in most cases. May be slightly increased for very small numbers of training examples and slightly decreased for very large numbers of training examples.
[in]	trainSearchParams	Parameters for search training (see description of TTrainSearchParams struct).
[out]	searchClf	Receives the handle of the generated classifier.

Returns: One of the return codes defined in TPolimagoTrainingError.

◆ PMTrainSearchClassifierGeneric()

TPolimagoTrainingError PMTrainSearchClassifierGeneric	(	TLEARNINGDATAACCESS	db,
		TProgress *	Progress,
		const char *	szPreproCode,
		double	lambda,
		TTrainSearchParams	trainSearchParams,
		TSCLF &	searchClf
	)

Generate a search classifier from a generic database access object.

Generate the access object using the function PMCreateLearningDataAccessSearch, specifying the callback routines that implement the database access.

Attention: The classifier object generated by this function must be cleared from memory with a ReleaseObject call (CVCImg.dll) once it is no longer needed.

Parameters

[in]	db	Specifies the training data set.
[in]	Progress	Progress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]	szPreproCode	Preprocessing to be used for training.
[in]	lambda	Ridge regression regularization constant. The default value 0.01 works well in most cases. May be slightly increased for very small numbers of training examples and slightly decreased for very large numbers of training examples.
[in]	trainSearchParams	Parameters for search training (see description of TTrainSearchParams struct).
[out]	searchClf	Receives the handle of the generated classifier.

Returns: One of the return codes defined in TPolimagoTrainingError.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ TGetLearningDataExampleClassLabel

◆ TGetLearningDataExampleClassLabelW

◆ TGetLearningDataExampleGeometry

◆ TGetLearningDataExamplePosition

◆ TGetLearningDataExampleVector

◆ TGetLearningDataFeatureWindow

◆ TGetLearningDataImage

◆ TGetLearningDataNumExamplesInImage

◆ TGetLearningDataNumImagePlanes

◆ TGetLearningDataNumImages

◆ TGetLearningDataOutputDimension

◆ TLEARNINGDATAACCESS

◆ TLearningDataFinalRelease

◆ TProgressReport

◆ TReleaseProgressReport

◆ TStartProgressReport

Enumeration Type Documentation

◆ TClassifierUsage

◆ TGroupSpec

◆ TInvarianceType

◆ TMapMode

◆ TPolimagoTrainingError

Function Documentation

◆ PMCreateLearningDataAccess()

◆ PMCreateLearningDataAccessSearch()

◆ PMCreateLearningDataAccessW()

◆ PMExtractFeatureImage()

◆ PMGetErrormessage()

◆ PMTrainClassifierFromMts()

◆ PMTrainClassifierFromSil()

◆ PMTrainClassifierGeneric()

◆ PMTrainSearchClassifierFromMts()

◆ PMTrainSearchClassifierFromSil()

◆ PMTrainSearchClassifierGeneric()