Find Matches

• Once a pattern is learned, use EMatcher::Match ^{.NET Python} to find it in an image.

• This returns a vector of EFoundPattern ^{.NET Python}. For each EFoundPattern:

  • Use GetScore ^{.NET Python} to get the score, between -1 and 1, see Correlation Mode for more details.

  • Use GetCenter ^{.NET Python}, GetScaleX ^{.NET Python}, GetScaleY ^{.NET Python} and GetAngle ^{.NET Python} to get the center, scale along and X and Y axis and angle of the match.

  • Use GetQuadrangle ^{.NET Python} to get its position.

  • Use GetLearntPatternIndex ^{.NET Python} to get the index of the corresponding learned pattern when several are learned.

  • Use Draw ^{.NET Python} to draw the match. The function can be tuned with:

    • SetDrawCenter ^{.NET Python} to draw the center.

    • SetDrawFeaturePoints ^{.NET Python} to draw the feature points.

    • SetDrawBoundingBox ^{.NET Python} to draw the bounding box.

    • SetDrawRegion ^{.NET Python} to draw the region.

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

• EasyMatch finds patterns in the image with 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.

• To set an isotropic scale, use EMatcher::SetMinScale ^{.NET Python} and EMatcher::SetMaxScale ^{.NET Python}.

• To set an anisotropic scale, use EMatcher::SetMinScaleX ^{.NET Python}, EMatcher::SetMaxScaleX ^{.NET Python}, EMatcher::SetMinScaleY ^{.NET Python} and EMatcher::SetMaxScaleY ^{.NET Python}.

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

Min Score and Max Positions

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

• It returns only EFoundPattern with a score above EMatcher::SetMinScore ^{.NET Python}.

• At most, it returns EMatcher::SetMaxPositions ^{.NET Python} results (as EFoundPattern).

• Use these parameters to avoid 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 the same contrast as at learn time, inverted contrast or both.

• By default, EasyMatch searches only matches with the same contrast as at learn time.

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 the inverse of the learn pattern) and 1 (perfect correlation with the learn pattern).

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 to adjust EMatcher::SetMaxInitialPositions ^{.NET Python} and/or EMatcher::SetInitialMinScore ^{.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}.

• In this case, you may have to 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 an 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}.