F_VN_FindTemplateWalshExp

Syntax

Definition:

FUNCTION F_VN_FindTemplateWalshExp_AngleRange : HRESULT
VAR_INPUT
    ipSrcImage         : ITcVnImage;
    ipTemplateImage    : ITcVnImage;
    ipMatches          : Reference To  ITcVnContainer;
    fMatchThreshold    : REAL;
    nProjections       : UDINT;
    fStartAngle        : LREAL;
    fStopAngle         : LREAL;
    nAngles            : UDINT;
    eOptions           : 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.
fStartAngle	LREAL	First search angle
fStopAngle	LREAL	Last search angle
nAngles	UDINT	Number of different search angles to be used
eOptions	UDINT	Flags controlling the matching process. (see ETcVnFindTemplateWalshOptions; default: TCVN_FTWO_NONE)
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 function F_VN_FindTemplateWalshExp_AngleRange is the expert variant of F_VN_FindTemplateWalsh_AngleRange and contains additional parameters. It 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.

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.

TCVN_FTWO_MATCH_OPPOSITE_RANGE: Performs the matching additionally with the opposite angles (rotated by 180°). This option is useful when it is unknown whether an object might be rotated by 180°. It effectively doubles the angle range being checked without having to search the entire 360° range.

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