F_VN_FindTemplateWalshExp

Syntax

Definition:

FUNCTION F_VN_FindTemplateWalshExp : HRESULT
VAR_INPUT
    ipSrcImage         : ITcVnImage;
    ipTemplateImage    : ITcVnImage;
    ipMatches          : Reference To  ITcVnContainer;
    fMatchThreshold    : REAL;
    nProjections       : UDINT;
    eOptions           : UDINT;
    nRotations         : UDINT;
    fScaleFactor       : REAL;
    eInterpolationType : ETcVnInterpolationType;
    ipMatchValues      : Reference To  ITcVnContainer;
    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 (container type depends on eOptions; ContainerType_Vector_TcVnRotatedRectangle or 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.
eOptions	UDINT	Flags controlling the matching process. (see ETcVnFindTemplateWalshOptions; default: TCVN_FTWO_NONE)
nRotations	UDINT	Number of rotations to be checked. (valid values: 1 (0°), 2 (0° and 180°), 4 (0°, 90°, 180°, and 270°), 8 (0°, 45°, ..., 315°), 16 (0°, 22.5°, ..., 337.5°), and 32 (0°, 11.25°, ..., 348.75°); default: 1)
fScaleFactor	REAL	Factor (0..1] to reduce source and template image width and height for better performance (but less accuracy!)
eInterpolationType	ETcVnInterpolationType	Image resize interpolation type (only used if fScaleFactor != 1, TCVN_IT_BILINEAR recommended for most cases)
ipMatchValues	Reference To ITcVnContainer	Optionally returns the matching values (ContainerType_Vector_REAL, same size and sort order as ipMatches. Set to 0 if not required.)
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_FindTemplateWalshExp function is the expert variant of F_VN_FindTemplateWalsh and contains additional parameters. It uses the Walsh transformation to localize all instances of a reference image (template) in the search image. The orientation of the objects found can be checked with a fixed step size, which results from the number of rotations to be checked in the range from 0° to 360°.

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.

Options

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

TCVN_FTWO_NONE: No special options.
TCVN_FTWO_FUSE_MATCHES: Combines hits of similar position and rotation. Setting this option is recommended. Deactivation can be useful for development and parameterization in order to view all raw detections.
TCVN_FTWO_ROTATED_RECTANGLE: Returns results directly as ContainerType_Vector_TcVnRotatedRectangle. The corresponding match values can be read separately using ipMatchValues.
TCVN_FTWO_SKIP_DC: Skips the DC component in the similarity calculation, which can improve robustness to lighting changes. Generally requires a higher number of projections.
TCVN_FTWO_WD_STOP_CORRECTION: Adjusts the match threshold heuristically if processing was interrupted by a watchdog abort.

Number of rotations to be checked

The number of rotation steps to be checked nNumRotations determines the angular resolution during matching. Valid values are:

1 (0°)
2 (0° and 180°)
4 (0°, 90°, 180° and 270°)
8 (0°, 45°, ..., 315°)
16 (0°, 22.5°, ..., 337.5°)
32 (0°, 11.25°, ..., 348.75°)

The output rotation angle of the final match can also lie between the defined rotation steps. If matches are found for several angle steps and the TCVN_FTWO_FUSE_MATCHES option is enabled, the final angle is determined by interpolation.

Scaling factor

The factor fScaleFactor (0 to 1.0) is used to reduce the resolution of the input and template image. Reducing the image size improves performance, but reduces the accuracy of the matching.

Interpolation type

The eInterpolationType parameter determines the method for image scaling (is only evaluated if fScaleFactor is not equal to 1). For most applications, TCVN_IT_BILINEAR is recommended.

Return of the match values

The ipMatchValues parameter is an optional return container (ContainerType_Vector_REAL) for the pure match values. It has the same length and sorting as ipMatches. If the TCVN_FTWO_ROTATED_RECTANGLE option is not used, these values are redundant as they are already contained in the return structures of ipMatches. If the separate output is not required, the parameter should be set to 0.

Examples

Walsh template matching with rotation

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