ClassesClasses | | Operators

create_uncalib_descriptor_modelT_create_uncalib_descriptor_modelCreateUncalibDescriptorModelCreateUncalibDescriptorModel (Operator)

Name

create_uncalib_descriptor_modelT_create_uncalib_descriptor_modelCreateUncalibDescriptorModelCreateUncalibDescriptorModel — Prepare a descriptor model for interest point matching.

Signature

create_uncalib_descriptor_model(Template : : DetectorType, DetectorParamName, DetectorParamValue, DescriptorParamName, DescriptorParamValue, Seed : ModelID)

Herror T_create_uncalib_descriptor_model(const Hobject Template, const Htuple DetectorType, const Htuple DetectorParamName, const Htuple DetectorParamValue, const Htuple DescriptorParamName, const Htuple DescriptorParamValue, const Htuple Seed, Htuple* ModelID)

void CreateUncalibDescriptorModel(const HObject& Template, const HTuple& DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, const HTuple& Seed, HTuple* ModelID)

void HDescriptorModel::HDescriptorModel(const HImage& Template, const HString& DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, Hlong Seed)

void HDescriptorModel::HDescriptorModel(const HImage& Template, const char* DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, Hlong Seed)

void HDescriptorModel::CreateUncalibDescriptorModel(const HImage& Template, const HString& DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, Hlong Seed)

void HDescriptorModel::CreateUncalibDescriptorModel(const HImage& Template, const char* DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, Hlong Seed)

HDescriptorModel HImage::CreateUncalibDescriptorModel(const HString& DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, Hlong Seed) const

HDescriptorModel HImage::CreateUncalibDescriptorModel(const char* DetectorType, const HTuple& DetectorParamName, const HTuple& DetectorParamValue, const HTuple& DescriptorParamName, const HTuple& DescriptorParamValue, Hlong Seed) const

static void HOperatorSet.CreateUncalibDescriptorModel(HObject template, HTuple detectorType, HTuple detectorParamName, HTuple detectorParamValue, HTuple descriptorParamName, HTuple descriptorParamValue, HTuple seed, out HTuple modelID)

public HDescriptorModel(HImage template, string detectorType, HTuple detectorParamName, HTuple detectorParamValue, HTuple descriptorParamName, HTuple descriptorParamValue, int seed)

void HDescriptorModel.CreateUncalibDescriptorModel(HImage template, string detectorType, HTuple detectorParamName, HTuple detectorParamValue, HTuple descriptorParamName, HTuple descriptorParamValue, int seed)

HDescriptorModel HImage.CreateUncalibDescriptorModel(string detectorType, HTuple detectorParamName, HTuple detectorParamValue, HTuple descriptorParamName, HTuple descriptorParamValue, int seed)

Description

The operator create_uncalib_descriptor_modelcreate_uncalib_descriptor_modelCreateUncalibDescriptorModelCreateUncalibDescriptorModelCreateUncalibDescriptorModel prepares a descriptor model of an image region, which is passed in the image TemplateTemplateTemplateTemplatetemplate, that can be used for descriptor-based matching. By a subsequent call of find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel a projective 2D transformation (homography) from TemplateTemplateTemplateTemplatetemplate to a search image can be obtained. The center of gravity of the domain region in TemplateTemplateTemplateTemplatetemplate is used as an origin of the model. In contrast to create_calib_descriptor_modelcreate_calib_descriptor_modelCreateCalibDescriptorModelCreateCalibDescriptorModelCreateCalibDescriptorModel, no calibrated camera is needed and hence the result of a subsequent matching is a 2D projection. Note that the part of the object that is visible in the TemplateTemplateTemplateTemplatetemplate image needs to be planar.

The descriptor model describes a set of points of interest. It stores their locations and discriminative descriptions of their local gray value neighborhood. The interest point extraction is parametrized by DetectorTypeDetectorTypeDetectorTypeDetectorTypedetectorType, DetectorParamNameDetectorParamNameDetectorParamNameDetectorParamNamedetectorParamName and DetectorParamValueDetectorParamValueDetectorParamValueDetectorParamValuedetectorParamValue. The respective descriptor around the interest points is parametrized by DescriptorParamNameDescriptorParamNameDescriptorParamNameDescriptorParamNamedescriptorParamName and DescriptorParamValueDescriptorParamValueDescriptorParamValueDescriptorParamValuedescriptorParamValue. The parameter SeedSeedSeedSeedseed seeds the random number generator, which is used during the construction of the descriptor implemented with randomized ferns. The returned ModelIDModelIDModelIDModelIDmodelID is a reference to the generated descriptor model. This model can be used for an efficient detection of instances of the learned template with find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel, allowing perspective transformation between model and search image. As descriptor-based matching relies on the existence of stable and discriminative points of interest, the object to be detected must be textured, but not in a repetitive way.

Detector parameters

As mentioned, the detector is used for the extraction of stable interest points within the image. By the parameter DetectorTypeDetectorTypeDetectorTypeDetectorTypedetectorType, it is possible to select the interest point operator to be used. Currently, points_lepetitpoints_lepetitPointsLepetitPointsLepetitPointsLepetit, points_harrispoints_harrisPointsHarrisPointsHarrisPointsHarris, and its binomial approximation points_harris_binomialpoints_harris_binomialPointsHarrisBinomialPointsHarrisBinomialPointsHarrisBinomial are supported ('lepetit', 'harris', 'harris_binomial'). In case of templates or search images with a low contrast, one of the harris point operators should be used. Depending on the selected DetectorTypeDetectorTypeDetectorTypeDetectorTypedetectorType, appropriate parameter names and values can be set in DetectorParamNameDetectorParamNameDetectorParamNameDetectorParamNamedetectorParamName and DetectorParamValueDetectorParamValueDetectorParamValueDetectorParamValuedetectorParamValue.

Possible parameter names for DetectorParamNameDetectorParamNameDetectorParamNameDetectorParamNamedetectorParamName and corresponding default values are:

'lepetit'"lepetit""lepetit""lepetit""lepetit":

['radius','check_neighbor', 'min_check_neighbor_diff','min_score','subpix']

[3, 1, 15, 30, 'interpolation']

'harris'"harris""harris""harris""harris":

['sigma_grad','sigma_smooth','alpha', 'threshold']

[ 0.7, 2.0, 0.08, 1000]

'harris_binomial'"harris_binomial""harris_binomial""harris_binomial""harris_binomial":

['mask_size_grd','mask_size_smooth', 'alpha','threshold','subpix']

[ 5, 15, 0.08, 1000, 'on']

Further details on the meaning of those parameters can be found in the descriptions of points_harrispoints_harrisPointsHarrisPointsHarrisPointsHarris, points_harris_binomialpoints_harris_binomialPointsHarrisBinomialPointsHarrisBinomialPointsHarrisBinomial and points_lepetitpoints_lepetitPointsLepetitPointsLepetitPointsLepetit, respectively. If an empty tuple is passed or a parameter is not provided in DetectorParamNameDetectorParamNameDetectorParamNameDetectorParamNamedetectorParamName, the above mentioned default values are taken.

While adjusting the operator parameters it should be aimed that a set of 50 to 450 feature points is extracted (depending on the texture and size of TemplateTemplateTemplateTemplatetemplate), which are uniformly distributed over the template's ROI. Therefore, it is recommended to run the point operator of choice in advance and visualize the results by gen_cross_contour_xldgen_cross_contour_xldGenCrossContourXldGenCrossContourXldGenCrossContourXld. In most cases it is sufficient to use the default setting.

Descriptor parameters

A point descriptor is a classifier, which builds characteristic descriptions of the gray-value neighborhood for interest points. Currently the descriptor is implemented with the so-called randomized ferns, which learns the polarity of the gray-value differences of pairs of pixels certain at random locations in the surrounding area of the interest point. The descriptor is later used in find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel to classify interest points in the search image, or in other words: to identify (match) potential model points in the search image.

The descriptor needs to store only the projectively stable interest points (which will appear in many projective views of the template). To assess the stability of the interest points, a simulation is performed: TemplateTemplateTemplateTemplatetemplate undergoes many affine transformations and points that can be extracted in most of the views are considered stable. The affine transformations are a good approximation of the projective transformations within a local neighborhood of the interest points.

The following descriptor parameters can be set with DescriptorParamNameDescriptorParamNameDescriptorParamNameDescriptorParamNamedescriptorParamName and DescriptorParamValueDescriptorParamValueDescriptorParamValueDescriptorParamValuedescriptorParamValue:

Descriptor size parameters:

'depth'"depth""depth""depth""depth":

depth of a classification fern. A deeper randomized fern can better discriminate interest points. However, the memory requirement for the fern grows by a factor 2 to the power of 'depth'"depth""depth""depth""depth". Typical values are [5 .. 11], default value is 11.

'number_ferns'"number_ferns""number_ferns""number_ferns""number_ferns":

number of fern structures used. Using more ferns increases the recognition robustness, however it also increases the runtime of the matching. If the memory needed for the descriptor should be small, many ferns with only a small depth should be used (e.g., 'number_ferns'"number_ferns""number_ferns""number_ferns""number_ferns"=150, 'depth'"depth""depth""depth""depth"=5). If detection speed is more important, fewer ferns of larger depth should be used (e.g., 'number_ferns'"number_ferns""number_ferns""number_ferns""number_ferns"=10, 'depth'"depth""depth""depth""depth"=11). Typical values are [1 .. 150], default value is 30.

'patch_size'"patch_size""patch_size""patch_size""patch_size":

side length of a quadratic neighborhood describing a point of interest. Too large values of this parameter can influence the run time. Typical values are [15 .. 33], default value is 17.

Summing up, the parameters 'depth'"depth""depth""depth""depth", 'number_ferns'"number_ferns""number_ferns""number_ferns""number_ferns" and 'patch_size'"patch_size""patch_size""patch_size""patch_size" allow a transparent control over detection robustness, speed and memory consumption.

Simulation parameters:

'tilt'"tilt""tilt""tilt""tilt":

switches on or off the projective transformations during the simulation phase. When switched on, the robustness of the model is improved and objects with bigger tilts can be found. When switched off, training time can be significantly reduced and the model is still able to recognize projectively invariant objects. Possible values are ['on'"on""on""on""on", 'off'"off""off""off""off"], default value is 'on'"on""on""on""on".

'min_rot'"min_rot""min_rot""min_rot""min_rot":

minimal angle of rotation around the normal vector of TemplateTemplateTemplateTemplatetemplate. Typical values are [-180 .. 0], default value is -180.

'max_rot'"max_rot""max_rot""max_rot""max_rot":

maximal angle of rotation around the normal vector of TemplateTemplateTemplateTemplatetemplate. Typical values are [0 .. 180], default value is 180.

'min_scale'"min_scale""min_scale""min_scale""min_scale":

minimal scale of TemplateTemplateTemplateTemplatetemplate. Typical values are [0.1 .. 1.0], default value is 0.5.

'max_scale'"max_scale""max_scale""max_scale""max_scale":

maximal scale of TemplateTemplateTemplateTemplatetemplate. Typical values are [1.0 .. 3.5], default value is 1.4.

The parameters 'min_rot'"min_rot""min_rot""min_rot""min_rot", 'max_rot'"max_rot""max_rot""max_rot""max_rot", 'min_scale'"min_scale""min_scale""min_scale""min_scale", and 'max_scale'"max_scale""max_scale""max_scale""max_scale" allow to manually set which affine transformed views of the template are used to train the descriptor. Setting these parameters is useful to reduce training time especially in combination with the parameter 'tilt'"tilt""tilt""tilt""tilt". Be aware that these parameters have direct influence on the results of find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel and therefore have to be set carefully. If, for example, the range of rotation is restricted from 'min_rot'"min_rot""min_rot""min_rot""min_rot" = -10 to 'max_rot'"max_rot""max_rot""max_rot""max_rot" = 10 it is not possible to find views of TemplateTemplateTemplateTemplatetemplate rotated by an angle outside that scope. A limited training range requires less ferns / ferns' depths to find TemplateTemplateTemplateTemplatetemplate. In such a case the number and depth of the ferns can be further reduced, which optimizes the model.

Remarks

Please note that depending on your hardware, the processing time for training the randomized ferns can vary between several seconds to some minutes. Therefore, a once trained model can be saved and loaded with write_descriptor_modelwrite_descriptor_modelWriteDescriptorModelWriteDescriptorModelWriteDescriptorModel and read_descriptor_modelread_descriptor_modelReadDescriptorModelReadDescriptorModelReadDescriptorModel.

The parameters and the location of the final descriptor points can be determined with get_descriptor_model_paramsget_descriptor_model_paramsGetDescriptorModelParamsGetDescriptorModelParamsGetDescriptorModelParams and get_descriptor_model_pointsget_descriptor_model_pointsGetDescriptorModelPointsGetDescriptorModelPointsGetDescriptorModelPoints.

create_uncalib_descriptor_modelcreate_uncalib_descriptor_modelCreateUncalibDescriptorModelCreateUncalibDescriptorModelCreateUncalibDescriptorModel stores the detector type, detector parameters, and descriptor parameters, which are used in every succeeding call of find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel. The reference point (origin) of the model is the center of gravity of the template's ROI. Its coordinates can be changed by set_descriptor_model_originset_descriptor_model_originSetDescriptorModelOriginSetDescriptorModelOriginSetDescriptorModelOrigin.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

TemplateTemplateTemplateTemplatetemplate (input_object)  singlechannelimage objectHImageHImageHobject (byte / uint2)

Input image whose domain will be used to create the model.

DetectorTypeDetectorTypeDetectorTypeDetectorTypedetectorType (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

The type of the detector.

Default value: 'lepetit' "lepetit" "lepetit" "lepetit" "lepetit"

List of values: 'harris'"harris""harris""harris""harris", 'harris_binomial'"harris_binomial""harris_binomial""harris_binomial""harris_binomial", 'lepetit'"lepetit""lepetit""lepetit""lepetit"

DetectorParamNameDetectorParamNameDetectorParamNameDetectorParamNamedetectorParamName (input_control)  attribute.name-array HTupleHTupleHtuple (string) (string) (HString) (char*)

The detector's parameter names.

Default value: []

List of values: 'alpha'"alpha""alpha""alpha""alpha", 'check_neighbor'"check_neighbor""check_neighbor""check_neighbor""check_neighbor", 'mask_size_grd'"mask_size_grd""mask_size_grd""mask_size_grd""mask_size_grd", 'mask_size_smooth'"mask_size_smooth""mask_size_smooth""mask_size_smooth""mask_size_smooth", 'min_check_neighbor_diff'"min_check_neighbor_diff""min_check_neighbor_diff""min_check_neighbor_diff""min_check_neighbor_diff", 'min_score'"min_score""min_score""min_score""min_score", 'radius'"radius""radius""radius""radius", 'sigma_grad'"sigma_grad""sigma_grad""sigma_grad""sigma_grad", 'sigma_smooth'"sigma_smooth""sigma_smooth""sigma_smooth""sigma_smooth", 'subpix'"subpix""subpix""subpix""subpix", 'threshold'"threshold""threshold""threshold""threshold"

DetectorParamValueDetectorParamValueDetectorParamValueDetectorParamValuedetectorParamValue (input_control)  attribute.value-array HTupleHTupleHtuple (integer / real / string) (int / long / double / string) (Hlong / double / HString) (Hlong / double / char*)

Values of the detector's parameters.

Default value: []

Suggested values: 0.08, 1, 1.2, 3, 15, 30, 1000, 'on'"on""on""on""on", 'off'"off""off""off""off", 'none'"none""none""none""none", 'interpolation'"interpolation""interpolation""interpolation""interpolation"

DescriptorParamNameDescriptorParamNameDescriptorParamNameDescriptorParamNamedescriptorParamName (input_control)  attribute.name-array HTupleHTupleHtuple (string) (string) (HString) (char*)

The descriptor's parameter names.

Default value: []

List of values: 'depth'"depth""depth""depth""depth", 'max_rot'"max_rot""max_rot""max_rot""max_rot", 'max_scale'"max_scale""max_scale""max_scale""max_scale", 'min_rot'"min_rot""min_rot""min_rot""min_rot", 'min_scale'"min_scale""min_scale""min_scale""min_scale", 'number_ferns'"number_ferns""number_ferns""number_ferns""number_ferns", 'patch_size'"patch_size""patch_size""patch_size""patch_size", 'tilt'"tilt""tilt""tilt""tilt"

DescriptorParamValueDescriptorParamValueDescriptorParamValueDescriptorParamValuedescriptorParamValue (input_control)  attribute.value-array HTupleHTupleHtuple (integer / real / string) (int / long / double / string) (Hlong / double / HString) (Hlong / double / char*)

Values of the descriptor's parameters.

Default value: []

Suggested values: 0.5, 1.4, 11, 21, 30, -180, 180, 'on'"on""on""on""on", 'off'"off""off""off""off"

SeedSeedSeedSeedseed (input_control)  integer HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

The seed for the random number generator.

Default value: 42

ModelIDModelIDModelIDModelIDmodelID (output_control)  descriptor_model HDescriptorModel, HTupleHTupleHtuple (integer) (IntPtr) (Hlong) (Hlong)

The handle to the descriptor model.

Possible Predecessors

points_lepetitpoints_lepetitPointsLepetitPointsLepetitPointsLepetit, points_harrispoints_harrisPointsHarrisPointsHarrisPointsHarris, reduce_domainreduce_domainReduceDomainReduceDomainReduceDomain

Possible Successors

get_descriptor_model_paramsget_descriptor_model_paramsGetDescriptorModelParamsGetDescriptorModelParamsGetDescriptorModelParams, find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel

See also

get_descriptor_model_paramsget_descriptor_model_paramsGetDescriptorModelParamsGetDescriptorModelParamsGetDescriptorModelParams, find_uncalib_descriptor_modelfind_uncalib_descriptor_modelFindUncalibDescriptorModelFindUncalibDescriptorModelFindUncalibDescriptorModel

References

V. Lepetit and P. Fua: “Keypoint Recognition using Randomized Trees.“ IEEE Transactions on Pattern Analysis and Machine Intelligence, Vol. 28, Nr. 9, pp. 1465-1479, 2006.
M. Ozuysal, P. Fua, and V. Lepetit: “Fast Keypoint Recognition in Ten Lines of Code.“ In Proceedings of Conference on Computer Vision and Pattern Recognition, 2007.

Module

Matching


ClassesClasses | | Operators