F_VN_MatchTemplateWalshExp

F_VN_MatchTemplateWalshExp 1:

Match a template image with every location in the source image (using the Walsh transform) and return the comparison results. (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.

Syntax

Definition:

FUNCTION F_VN_MatchTemplateWalshExp : HRESULT
VAR_INPUT
    ipSrcImage      : ITcVnImage;
    ipTemplateImage : ITcVnImage;
    ipResultImage   : Reference To  ITcVnImage;
    nProjections    : UDINT;
    eOptions        : UDINT;
    nRotations      : 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)

ipResultImage

Reference To ITcVnImage

Returns the result image (REAL, normalized to [0..1], nRotations channel(s), dimensions: (ipSrcImage.width - ipTemplateImage.width + 1) x (ipSrcImage.height - ipTemplateImage.height + 1). The best match is the global minimum over all channels. The position in ipResultImage is the top-left corner of ipTemplateImage position in ipSrcImage. The rotation can be inferred from the channel the minimum is found in.)

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.

eOptions

UDINT

Flags controlling the matching process. (see ETcVnMatchTemplateWalshOptions)

nRotations

UDINT

Number of rotations to be checked. (valid values: 1 (0°), 2 (0° and 180°), and 4 (0°, 90°, 180°, and 270°; only for square images))

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_MatchTemplateWalshExp function is the expert variant of F_VN_MatchTemplateWalsh and contains additional parameters. It uses the Walsh transformation to localize all instances of a reference image (template) in the search image and returns the similarity values as the result image. In contrast to the standard variant, the template can be checked in several rotation steps.

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.

Result image

The resulting image ipResultImage is a 1-channel REAL image with the following dimensions:

  • Width: ipSrcImage.Width - ipTemplateImage.Width + 1
  • Height: ipSrcImage.Height - ipTemplateImage.Height + 1
  • Channels: One channel per tested rotation step (default: 1)

Each pixel value represents the similarity between the template and the corresponding image section in the input image. A smaller value means a higher match. The global minimum across all channels marks the best match. The position of the minimum in the result image corresponds to the top left-hand corner of the template position in the input image.

For example, F_VN_MinPixelValue can be used to determine the minimum pixel value and the associated position and channel.

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.

Options

With eOptions, options (ETcVnMatchTemplateWalshOptions) can be specified that influence the functionality and result output. Multiple options can be combined using an OR operator. The following options are available:

Number of rotations to be checked

The nRotations parameter specifies the number of rotation steps to be checked and thus defines both the angular positions examined and the resulting number of channels in the result image. The channel in which the minimum is found corresponds to the rotation angle of the match. Valid values are:

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