ClassesClassesClassesClasses | | | | Operators

create_templatecreate_templateCreateTemplatecreate_templateCreateTemplateCreateTemplate (Operator)

Name

create_templatecreate_templateCreateTemplatecreate_templateCreateTemplateCreateTemplate — Preparing a pattern for template matching.

Warning

create_templatecreate_templateCreateTemplatecreate_templateCreateTemplateCreateTemplate is obsolete and is only provided for reasons of backward compatibility. New applications should use the shape-based or NCC-based operators instead.

Signature

create_template(Template : : FirstError, NumLevel, Optimize, GrayValues : TemplateID)

Herror create_template(const Hobject Template, const Hlong FirstError, const Hlong NumLevel, const char* Optimize, const char* GrayValues, Hlong* TemplateID)

Herror T_create_template(const Hobject Template, const Htuple FirstError, const Htuple NumLevel, const Htuple Optimize, const Htuple GrayValues, Htuple* TemplateID)

Herror create_template(Hobject Template, const HTuple& FirstError, const HTuple& NumLevel, const HTuple& Optimize, const HTuple& GrayValues, Hlong* TemplateID)

HTemplate HImage::CreateTemplate(const HTuple& FirstError, const HTuple& NumLevel, const HTuple& Optimize, const HTuple& GrayValues) const

void HTemplate::CreateTemplate(const HImage& Template, const HTuple& FirstError, const HTuple& NumLevel, const HTuple& Optimize, const HTuple& GrayValues)

void CreateTemplate(const HObject& Template, const HTuple& FirstError, const HTuple& NumLevel, const HTuple& Optimize, const HTuple& GrayValues, HTuple* TemplateID)

void HTemplate::HTemplate(const HImage& Template, Hlong FirstError, Hlong NumLevel, const HString& Optimize, const HString& GrayValues)

void HTemplate::HTemplate(const HImage& Template, Hlong FirstError, Hlong NumLevel, const char* Optimize, const char* GrayValues)

void HTemplate::CreateTemplate(const HImage& Template, Hlong FirstError, Hlong NumLevel, const HString& Optimize, const HString& GrayValues)

void HTemplate::CreateTemplate(const HImage& Template, Hlong FirstError, Hlong NumLevel, const char* Optimize, const char* GrayValues)

HTemplate HImage::CreateTemplate(Hlong FirstError, Hlong NumLevel, const HString& Optimize, const HString& GrayValues) const

HTemplate HImage::CreateTemplate(Hlong FirstError, Hlong NumLevel, const char* Optimize, const char* GrayValues) const

void HOperatorSetX.CreateTemplate(
[in] IHUntypedObjectX* Template, [in] VARIANT FirstError, [in] VARIANT NumLevel, [in] VARIANT Optimize, [in] VARIANT GrayValues, [out] VARIANT* TemplateID)

void HTemplateX.CreateTemplate(
[in] IHImageX* Template, [in] Hlong FirstError, [in] Hlong NumLevel, [in] BSTR Optimize, [in] BSTR GrayValues)

IHTemplateX* HImageX.CreateTemplate(
[in] Hlong FirstError, [in] Hlong NumLevel, [in] BSTR Optimize, [in] BSTR GrayValues)

static void HOperatorSet.CreateTemplate(HObject template, HTuple firstError, HTuple numLevel, HTuple optimize, HTuple grayValues, out HTuple templateID)

public HTemplate(HImage template, int firstError, int numLevel, string optimize, string grayValues)

void HTemplate.CreateTemplate(HImage template, int firstError, int numLevel, string optimize, string grayValues)

HTemplate HImage.CreateTemplate(int firstError, int numLevel, string optimize, string grayValues)

Description

The operator create_templatecreate_templateCreateTemplatecreate_templateCreateTemplateCreateTemplate preprocesses a pattern (TemplateTemplateTemplateTemplateTemplatetemplate), which is passed as an image, for the template matching. After the transformation, a number (TemplateIDTemplateIDTemplateIDTemplateIDTemplateIDtemplateID) is assigned to the template for being used in the further process. The shape and the size of TemplateTemplateTemplateTemplateTemplatetemplate can be chosen arbitrarily. You have to be aware, that the matching is only applied to that part of an image where TemplateTemplateTemplateTemplateTemplatetemplate fits completely into the image.

The template has been chosen such that it contains no pixels of the (changing) background. Here you can make use of the arbitrary shape of a template which is not restricted to a rectangle. To create a template region you can use segmentation operators like thresholdthresholdThresholdthresholdThresholdThreshold or one of the draw_* operators. In the case of sub pixel accurate matching TemplateTemplateTemplateTemplateTemplatetemplate has in addition to be one pixel smaller than the pattern (i.e. one pixel border to the changing background). This can be done e.g. by applying the operator erosion_circleerosion_circleErosionCircleerosion_circleErosionCircleErosionCircle.

The parameter NumLevelNumLevelNumLevelNumLevelNumLevelnumLevel specifies the number of pyramid levels (NumLevelNumLevelNumLevelNumLevelNumLevelnumLevel = 1 means only original gray values) which can be used for matching. The number of levels used later for matching will be below or equal this value. If the pattern becomes too small due to zooming, the maximum number of pyramid levels is automatically reduced (without error message).

The parameter GrayValuesGrayValuesGrayValuesGrayValuesGrayValuesgrayValues defines, whether the original gray values ('original'"original""original""original""original""original", 'normalized'"normalized""normalized""normalized""normalized""normalized") or the edge amplitude ('gradient'"gradient""gradient""gradient""gradient""gradient", 'sobel'"sobel""sobel""sobel""sobel""sobel") is used. With 'original'"original""original""original""original""original" the sum of the differences is used as feature which is very stable and fast if there is no change in illumination. 'normalized'"normalized""normalized""normalized""normalized""normalized" is used if the illumination changes. The method is a bit slower and not quite as stable. Note that 'normalized'"normalized""normalized""normalized""normalized""normalized" allows to compensate additive illumination changes. If also multiplicative variations of the gray values occur, correlation-based matching should be used (create_ncc_modelcreate_ncc_modelCreateNccModelcreate_ncc_modelCreateNccModelCreateNccModel). If there is no change in illumination the mode 'original'"original""original""original""original""original" should be used. The edge amplitude is another method to be invariant to changes in illumination. The disadvantage is the increased execution time and the higher sensitivity to changes in the shape of the pattern. The mode 'gradient'"gradient""gradient""gradient""gradient""gradient" is slightly faster but more sensitive to noise.

The maximum error for matching has typically to be chosen higher when using the edge amplitude. The mode chosen by GrayValuesGrayValuesGrayValuesGrayValuesGrayValuesgrayValues leads automatically to calling the appropriate filter during the matching, if necessary.

As an alternative to the gradient approach the operator set_offset_templateset_offset_templateSetOffsetTemplateset_offset_templateSetOffsetTemplateSetOffsetTemplate can be used, if the change in illumination is known.

The parameter OptimizeOptimizeOptimizeOptimizeOptimizeoptimize specifies if the pattern has to be optimized for runtime. This optimization results in a longer time to create the template but reduces the time for matching. In addition the optimization leads to a more stable matching, i.e., the possibilty to miss good matches is reduced. The optimization process selects the most stable and significant gray values to be tested first during the matching process. Using this technique a wrong match can be eliminated very early.

The reference position for the template is its center of gravity. I.e. if you apply the template to the original image the center of gravity is returned. This default reference can be adapted using the operator set_reference_templateset_reference_templateSetReferenceTemplateset_reference_templateSetReferenceTemplateSetReferenceTemplate.

In sub pixel mode a special position correction is calculated which is added after each matching: The template is applied to the original image and the difference between the found position and the center of gravity is used as a correction vector. This is important for patterns in a textured context or for asymmetric pattern. For most templates this correction vector is near null.

If the pattern is no longer used, it has to be freed by the operator clear_templateclear_templateClearTemplateclear_templateClearTemplateClearTemplate in order to deallocate the memory.

Before the use of the template, which is stored independently of the image size, it can be adapted explicitly to the size of a definite image size by using adapt_templateadapt_templateAdaptTemplateadapt_templateAdaptTemplateAdaptTemplate.

Parallelization

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

TemplateTemplateTemplateTemplateTemplatetemplate (input_object)  singlechannelimage objectHImageHImageHImageHImageXHobject (byte)

Input image whose domain will be processed for the pattern matching.

FirstErrorFirstErrorFirstErrorFirstErrorFirstErrorfirstError (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Not yet in use.

Default value: 255

List of values: 255

NumLevelNumLevelNumLevelNumLevelNumLevelnumLevel (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Maximal number of pyramid levels.

Default value: 4

List of values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

OptimizeOptimizeOptimizeOptimizeOptimizeoptimize (input_control)  string HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

Kind of optimizing.

Default value: 'sort' "sort" "sort" "sort" "sort" "sort"

List of values: 'none'"none""none""none""none""none", 'sort'"sort""sort""sort""sort""sort"

GrayValuesGrayValuesGrayValuesGrayValuesGrayValuesgrayValues (input_control)  string HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

Kind of grayvalues.

Default value: 'original' "original" "original" "original" "original" "original"

List of values: 'gradient'"gradient""gradient""gradient""gradient""gradient", 'normalized'"normalized""normalized""normalized""normalized""normalized", 'original'"original""original""original""original""original", 'sobel'"sobel""sobel""sobel""sobel""sobel"

TemplateIDTemplateIDTemplateIDTemplateIDTemplateIDtemplateID (output_control)  template HTemplate, HTupleHTupleHTemplate, HTupleHTemplateX, VARIANTHtuple (integer) (IntPtr) (Hlong) (Hlong) (Hlong) (Hlong)

Template number.

Result

If the parameters are valid, the operator create_templatecreate_templateCreateTemplatecreate_templateCreateTemplateCreateTemplate returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.

Possible Predecessors

draw_regiondraw_regionDrawRegiondraw_regionDrawRegionDrawRegion, reduce_domainreduce_domainReduceDomainreduce_domainReduceDomainReduceDomain, thresholdthresholdThresholdthresholdThresholdThreshold

Possible Successors

adapt_templateadapt_templateAdaptTemplateadapt_templateAdaptTemplateAdaptTemplate, set_reference_templateset_reference_templateSetReferenceTemplateset_reference_templateSetReferenceTemplateSetReferenceTemplate, clear_templateclear_templateClearTemplateclear_templateClearTemplateClearTemplate, write_templatewrite_templateWriteTemplatewrite_templateWriteTemplateWriteTemplate, set_offset_templateset_offset_templateSetOffsetTemplateset_offset_templateSetOffsetTemplateSetOffsetTemplate, best_matchbest_matchBestMatchbest_matchBestMatchBestMatch, best_match_mgbest_match_mgBestMatchMgbest_match_mgBestMatchMgBestMatchMg, fast_matchfast_matchFastMatchfast_matchFastMatchFastMatch, fast_match_mgfast_match_mgFastMatchMgfast_match_mgFastMatchMgFastMatchMg

Alternatives

create_ncc_modelcreate_ncc_modelCreateNccModelcreate_ncc_modelCreateNccModelCreateNccModel, create_template_rotcreate_template_rotCreateTemplateRotcreate_template_rotCreateTemplateRotCreateTemplateRot, read_templateread_templateReadTemplateread_templateReadTemplateReadTemplate

Module

Matching


ClassesClassesClassesClasses | | | | Operators