Find Matches

• Once a pattern is learned, it can be found in an image by calling EMatcher::Match ^{.NET Python}.

• This returns a vector of EFoundPattern ^{.NET Python}. Each EFoundPattern contains:

  • A Score ^{.NET Python} between -1 and 1, see Correlation Mode for more details.

  • A Center ^{.NET Python}, ScaleX ^{.NET Python}, ScaleY ^{.NET Python} and Angle ^{.NET Python}.

  • A Position ^{.NET Python}.

  • The index ^{.NET Python} of the corresponding learned pattern when several are learned.

  • A draw function ^{.NET Python} that optionally draws the center ^{.NET Python}, the bounding box ^{.NET Python} and the region used for learning ^{.NET Python} (if there was one).

Hint

To speed up the search process, you can also use multicore processing. This is especially interesting when you use EasyMatch with angle and scale tolerances.

Matching Workflow

        flowchart TD
    A[Acquire an image]
    A --> B[Call the **Match** method]
    B --> C[Display or process the found instances]
    

Matching Parameters

Min/Max Angle

• The patterns found in the image can have an angle between EMatcher::SetMinAngle ^{.NET Python} and EMatcher::SetMaxAngle ^{.NET Python}.

• By default, MinAngle = MaxAngle = 0 to enable faster processing.

Min/Max Scale

• The patterns found in the image can also have an isotropic (ScaleX = ScaleY) or anisotropic (ScaleX != ScaleY) scale.

• The isotropic scale is set by: EMatcher::SetMinScale ^{.NET Python} and EMatcher::SetMaxScale ^{.NET Python}.

• The anisotropic scale is set by EMatcher::SetMinScaleX ^{.NET Python}, EMatcher::SetMaxScaleX ^{.NET Python}, EMatcher::SetMinScaleY ^{.NET Python}and EMatcher::SetMaxScaleY ^{.NET Python}.

• By default, no scale is applied to enable faster processing.

Min Score and Max Positions

EasyMatch returns a vector of EFoundPattern, sorted in decreasing Score order.

• Only EFoundPattern whose score is above EMatcher::SetMinScore ^{.NET Python} are returned.

• At most EMatcher::SetMaxPositions ^{.NET Python} results (as EFoundPattern) are returned.

• Use these parameters to get rid of false positives in your images.

Contrast Mode

• Lighting effects can cause an object to appear with inverted contrast.

• Use EMatcher::SetContrastMode ^{.NET Python} to search for matches with same contrast, inverted contrast or both.

• By default, only matches with the same contrast are searched.

Match Timeout

EMatcher::Match ^{.NET Python} possesses a timeout:

• Use EMatcher::SetMatchTimeOut ^{.NET Python} to add a time limit to the method EMatcher::Match ^{.NET Python}.

• If the timeout is reached, an exception is thrown and the processing stops.

Note

This timeout mechanism is used to prevent the application from freezing while tuning parameters. This is especially useful in eVision Studio. Note that this does not correspond to the behavior of code reader timeouts, which aim to prevent long processing times in production settings.

Advanced Parameters

Max Overlap

EasyMatch can filter out instances that completely or partially overlap with each other in the search results if EMatcher::GetMaxOverlap ^{.NET Python} is less than 1.0.

• The overlap is defined as the area of the intersection of the two instances divided by the area of the smallest instance.

• The maximum allowed overlap can take any value between 0 (no overlap allowed) and 1 (complete overlap allowed).

• By default, all overlaps are allowed (MaxOverlap = 1).

Correlation Mode

EasyMatch computes the score of an EFoundPattern by using a correlation metric. Several correlation metrics are available through EMatcher::SetCorrelationMode ^{.NET Python}:

• By default, ECorrelationMode_Normalized ^{.NET Python} is used. This correlation is unsensitive to changes in intensity (additive offset of the pixel values) and contrast (multiplicative gain of the pixel values).

• ECorrelationMode_Standard ^{.NET Python} is sensitive to changes in intensity and contrast.

• ECorrelationMode_OffsetNormalized ^{.NET Python} is unsensitive to changes in intensity and sensitive to changes in contrast.

• ECorrelationMode_GainNormalized ^{.NET Python} is sensitive to changes in intensity and unsensitive to changes in contrast.

• Each correlation mode returns a Score between -1 (perfect correlation with inverse of the match) and 1 (perfect correlation with match).

Extension

• EasyMatch can match patterns that are partially outside of the matching image.

• This feature is disabled by default. Use the parameter EMatcher::SetExtension ^{.NET Python} to enable and set it.

Initial Min Score and Initial Max Positions

• EasyMatch returns at most Max Positions results (as EFoundPattern) whose score is above Min Score, see here.

• However, candidates are filtered before the last stage of the pyramid to limit processing time.

• By default, these intermediate filtering values are computed from EMatcher::SetMaxPositions ^{.NET Python} and EMatcher::SetMinScore ^{.NET Python}.

• If EasyMatch does not manage to find (all of) the instances of the pattern in the image, try modifying EMatcher::SetMaxInitialPositions ^{.NET Python} and/or EMatcher::GetInitialMinScore ^{.NET Python}.

Early Candidate Rejection

• EasyMatch filters out candidates at early stages of the pyramid to limit processing time.

• If EasyMatch does not manage to find (all of) the instances of the pattern in the image, you can try to disable this filtering with EMatcher::SetEnableEarlyCandidateRejection ^{.NET Python}

• You might have to then increase EMatcher::SetMaxInitialPositions ^{.NET Python} to compensate for the new candidates.

Final Reduction

• Use EMatcher::SetFinalReduction ^{.NET Python} to stop the iterative position refinement in the pyramid before reaching the initial image.

• This setting is interesting if speed is important and having a coarse location is sufficient for your application.

• Note that the best candidate at reduction i is not necessarily the best candidate in the initial image, so setting this too aggressively can result in incorrect locations and not just coarse ones.

Interpolate

• By default, EasyMatch performs interpolation at the last reduction of the pyramid to achieve sub-pixel accuracy.

• If speed is more important than accuracy for your application, you may disable this interpolation with EMatcher::SetInterpolate ^{.NET Python}.