F_VN_FindTemplateWalsh

F_VN_FindTemplateWalsh 1:

Match a template image with every location in the source image (using the Walsh transform) and evaluate the comparison results. Returns a sorted list of possible matches (best match first).
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.

Syntax

Definition:

FUNCTION F_VN_FindTemplateWalsh : HRESULT
VAR_INPUT
    ipSrcImage      : ITcVnImage;
    ipTemplateImage : ITcVnImage;
    ipMatches       : Reference To  ITcVnContainer;
    fMatchThreshold : REAL;
    nProjections    : UDINT;
    hrPrev          : HRESULT;
END_VAR

 Inputs

Name

Type

Description

ipSrcImage

ITcVnImage

Source image (USINT or SINT, 1 or 3 channels)

ipTemplateImage

ITcVnImage

Template image (same type as ipSrcImage, smaller width and height)

ipMatches

Reference To ITcVnContainer

Returns the matching positions (ContainerType_Vector_TcVnVector4_REAL, where each element contains the center (x, y), the rotation angle in degrees, and the matching value of ipTemplateImage in ipSrcImage; container elements sorted by relevance (best match first))

fMatchThreshold

REAL

Threshold to separate relevant from irrelevant matches (0..1, 1.0 would be a perfect match.)

nProjections

UDINT

Number of Walsh projections to be used. The higher nProjections the more details are considered for matching. As the most relevant information is captured by the first Walsh projections, a small number (e.g., 5, 10, 25, or 50) is sufficient for many use cases. Each projection requires additional computation time. Therefore, it is advantageous to choose a low number of Walsh projections as long as the matching requirements are fulfilled. The allowed maximum of nProjections is determined by the width and the height of the template image.

hrPrev

HRESULT

HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

 Return value

HRESULT

Further information

The F_VN_FindTemplateWalsh function uses the Walsh transformation to localize all instances of a reference image (template) in the search image.

Parameter

Input image

The input image ipSrcImage must be a 1-channel or 3-channel image of the type USINT or SINT. With a 3-channel image, matching is performed jointly in all three channels, which also results in more processing time.

Template image

The template image ipTemplateImage must be of the same type as ipSrcImage and have smaller dimensions (height and width) than the input image.

List of match positions found

All matches found in the input image are sorted according to their match value (best match first) and returned in the container ipMatches of type ContainerType_Vector_TcVnVector4_REAL. Each TcVnVector4_REAL contains the coordinates of the center, the rotation in degrees and the match value (fX, fY, fAngleDeg, fMatchValue).

Match threshold value

The threshold value fMatchThreshold (0 to 1.0) can be used to separate irrelevant from relevant matches, with 1.0 corresponding to a perfect match. The value depends on the nature of the input image and the selected parameters and must be adjusted accordingly.

Number of Walsh projections

The nProjections parameter specifies how many Walsh projections are used for matching. Low projection counts primarily capture coarse image structures, while higher projection counts increasingly capture finer details but increase processing time. Therefore, nProjections should be set as low as possible, but as high as necessary. In many applications, 5-50 projections are sufficient. The permitted upper limit of nProjections is limited by the width and height of the template image.

Related functions

  • F_VN_FindTemplateWalsh(Exp): Searches for a template in the input image and returns a sorted list of matches found.
  • F_VN_FindTemplateWalsh(Exp)_AngleRange: As F_VN_FindTemplateWalsh(Exp), but with a freely definable angle range and any number of angle steps for targeted runtime and accuracy optimization.
  • F_VN_MatchTemplateWalsh(Exp): Compares a template with each location in the input image and returns the raw result image for application-specific post-processing.

Required License

TC3 Vision Matching