Polimago (Polimago.dll) 15.0
Training

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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImageIndexIndex of the image in which the example is located.
[in]ExampleIndexIndex of the example for which to determine the label.
[in]szLabelPointer to the buffer into which the string may be copied. Please make sure to include zero termination of that buffer.
[in,out]lenSize 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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImageIndexIndex of the image in which the example is located.
[in]ExampleIndexIndex of the example for which to determine the label.
[in]szLabelPointer 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]lenSize 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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImageIndexIndex of the image in which the example is located.
[in]ExampleIndexIndex of the example for which to determine the geometrical situation.
[out]SpecificationSpecification 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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImageIndexIndex of the image in which the example is located.
[in]ExampleIndexIndex of the example for which to determine the geometrical situation.
[out]Xx-coordinate at which the example is located.
[out]Yx-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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImageIndexIndex of the image in which the example is located.
[in]ExampleIndexIndex of the example for which Polimago wants to know the regression vector.
[in]vectorPointer 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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[out]FWLLeft edge of the feature window (should be zero or less than zero).
[out]FWTTop edge of the feature window (should be zero or less than zero).
[out]FWRRight edge of the feature window (should be zero or greater than zero).
[out]FWBBottom 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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImageIndexIndex 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]pPrivatePointer to the internally used data (see description of PMCreateLearningDataAccess).
[in]ImgIndexIndex 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]pPrivatePointer 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]pPrivatePointer 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]pPrivatePointer 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]PPrivatePointer to user definable data as given in the TProgress structure.
[in]IDNumber 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]PPrivatePointer to user definable data as given in the TProgress structure.
[in]IDNumber 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]PPrivatePointer to user definable data as given in the TProgress structure.
[in]IDNumber identifying a progress phase.
[in]CaptionPrintable name of the progress phase that is being started.
[in]TotalTotal number of steps of which the new progress phase consists.

Enumeration Type Documentation

◆ 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

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

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]pPrivatePrivate data pointer for use with the learning data access object.
[in]getNumImagePlanesCallback that specifies the number of image planes Polimago should use for training. Must not be NULL.
[in]getImageFromImageIndexCallback that allows Polimago to retrieve specific training images. Must not be NULL.
[in]getNumImagesCallback with which Polimago queries the total number of images available for training. Must not be NULL.
[in]getNumExamplesInImageCallback with which Polimago determines how many examples are present in a given image. Must not be NULL.
[in]getExamplePositionCallback Polimago uses to determine the position of an example. Must not be NULL.
[in]getClassLabelCallback 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]getOutputDimensionCallback 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]getFeatureWindowCallback with which Polimago determines the feature window to used for training. Must not be NULL.
[in]finalReleaseCallback 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]getExampleVectorCallback 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]pPrivatePrivate data pointer for use with the learning data access object.
[in]getNumImagePlanesCallback that specifies the number of image planes Polimago should use for training. Must not be NULL.
[in]getImageFromImageIndexCallback that allows Polimago to retrieve specific training images. Must not be NULL.
[in]getNumImagesCallback with which Polimago queries the total number of images available for training. Must not be NULL.
[in]getNumExamplesInImageCallback with which Polimago determines how many examples are present in a given image. Must not be NULL.
[in]getExampleGeometryCallback Polimago uses to determine the position and 2D pose of an example. Must not be NULL.
[in]getFeatureWindowCallback with which Polimago determines the feature window to used for training. Must not be NULL.
[in]finalReleaseCallback 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]pPrivatePrivate data pointer for use with the learning data access object.
[in]getNumImagePlanesCallback that specifies the number of image planes Polimago should use for training. Must not be NULL.
[in]getImageFromImageIndexCallback that allows Polimago to retrieve specific training images. Must not be NULL.
[in]getNumImagesCallback with which Polimago queries the total number of images available for training. Must not be NULL.
[in]getNumExamplesInImageCallback with which Polimago determines how many examples are present in a given image. Must not be NULL.
[in]getExamplePositionCallback Polimago uses to determine the position of an example. Must not be NULL.
[in]getClassLabelCallback 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]getOutputDimensionCallback 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]getFeatureWindowCallback with which Polimago determines the feature window to used for training. Must not be NULL.
[in]finalReleaseCallback 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]getExampleVectorCallback 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]sourceImage to extract from.
[in]featureMapTraining sample definition to use.
[in]XPosition at which to extract.
[in]YPosition at which to extract.
[in]MTransformation to apply during extraction.
[out]imgOutimage.
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]errorCodeNumerical error code returned by the classifier training functions (see TPolimagoTrainingError).
[in]szBufferDestination 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]lenLength (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]mtsSpecifies the training data set - in this case a sample image list.
[in]ProgressProgress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]usageClassifier usage - regression, 1v1 or 1vall classification (see description of TClassifierUsage). Note that CU_Regression is not permitted here.
[in]szPreproCodePreprocessing to be used for training code.
[in]featureResolutionDetermines 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]lambdaRidge 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]interpolateImage interpolation mode for feature extraction. implies simple truncation of fractional coordinates, TRUE (recommended) implies bilinear interpolation.
[out]ClfReceives 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]silSpecifies the training data set - in this case a sample image list.
[in]ProgressProgress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]usageClassifier 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]szPreproCodePreprocessing to be used for training code.
[in]featureResolutionDetermines 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]lambdaRidge 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]interpolateImage interpolation mode for feature extraction. implies simple truncation of fractional coordinates, TRUE (recommended) implies bilinear interpolation.
[out]ClfReceives 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]dbSpecifies the training data set.
[in]ProgressProgress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]usageClassifier 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]szPreproCodePreprocessing to be used for training code.
[in]featureResolutionDetermines 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]lambdaRidge 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]interpolateImage interpolation mode for feature extraction. implies simple truncation of fractional coordinates, TRUE (recommended) implies bilinear interpolation.
[out]ClfReceives 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]mtsTraining data set.
[in]ProgressProgress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]szPreproCodePreprocessing to be used for training.
[in]lambdaRidge 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]trainSearchParamsParameters for search training (see description of TTrainSearchParams struct).
[out]searchClfReceives 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]silTraining data set.
[in]ProgressProgress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]szPreproCodePreprocessing to be used for training.
[in]lambdaRidge 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]trainSearchParamsParameters for search training (see description of TTrainSearchParams struct).
[out]searchClfReceives 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]dbSpecifies the training data set.
[in]ProgressProgress callback structure for progress reports. May be used to show training progress on the user interface (see description of TProgress).
[in]szPreproCodePreprocessing to be used for training.
[in]lambdaRidge 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]trainSearchParamsParameters for search training (see description of TTrainSearchParams struct).
[out]searchClfReceives the handle of the generated classifier.
Returns
One of the return codes defined in TPolimagoTrainingError.