F_VN_FindTemplateWalsh_AngleRange

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_AngleRange : HRESULT
VAR_INPUT
    ipSrcImage      : ITcVnImage;
    ipTemplateImage : ITcVnImage;
    ipMatches       : Reference To  ITcVnContainer;
    fMatchThreshold : REAL;
    nProjections    : UDINT;
    fStartAngle     : LREAL;
    fStopAngle      : LREAL;
    nAngles         : 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.
fStartAngle	LREAL	First search angle
fStopAngle	LREAL	Last search angle
nAngles	UDINT	Number of different search angles to be used
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_AngleRange function uses the Walsh transformation to localize all instances of a reference image (template) in the search image. It limits the search range for object rotation to a freely definable angular range with a variable step size. This allows angular accuracy and runtime to be optimized in a targeted manner. If the angular range of the object being searched for is not known or cannot be restricted, F_VN_FindTemplateWalsh should be used.

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.

Angle range

The search range for the object rotation is defined by fStartAngle and fStopAngle as LREAL values in degrees. Both parameters specify the outer limits of the angle range being checked. If the search range is set too narrow, there is a risk that objects actually present outside the range will not be recognized. It is advisable to allow for a sufficient tolerance buffer.

Number of angular steps

The nAngles parameter determines the number of evenly distributed search angles within the defined angle range. In contrast to F_VN_FindTemplateWalsh, any number can be selected here. This enables a finer angular resolution in a defined range.

Example: With fStartAngle = -30°, fStopAngle = 30° and nAngles = 13, the angles -30°, -25°, -20°, ..., +25°, +30° are checked.

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