# Find Matches * Once a pattern is learned, it can be found in an image by calling [`EMatcher::Match`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#ac4c97be7341241ee12a14b705fb1d150) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a753e5bd7a5a267f3119986f1b5c6235b) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#aa146cdcdcfdb2d330ca60014db506cc1). * This returns a vector of [`EFoundPattern`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html). Each `EFoundPattern` contains: * A [`Score`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#a26fc1f189d2b207f0d9e681296b5e142) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#afffb43eccd8aee7cb7c747d1e53c0964) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a57ae1622643621d5c1e9e9ed3c1fffee) between `-1` and `1`, see [Correlation Mode]() for more details. * A [`Center`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#add106e12cba37e0bc4d2eaa55e673c76) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a4044e9a13bb3d8be3cde2241825d3c5b) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a1b30958eac9216d2bbb3610e6ff0cf3c), [`ScaleX`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#ab3c2712a83f1fa60c19fd2c50236d2c0) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a5eabdcfdfa9d2f2ecf7db57ab076e85b) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a2c8f95bfeec7ee7907b795c64e92d83b), [`ScaleY`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#abe7e8663b36e28b0c1ce3777d901420b) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a94d31f109d4ff78b2e01591115e96606) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#aebedfeb1f19863dd22806e3fa77e7610) and [`Angle`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#aa3477a2fdb73930c1ab2933dc18aa3cd) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a44675957b29d9835ca3ec78d2e140971) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a18a62e1b305b7f3e6a929f1fb4a5d40e). * A [`Position`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#ae334e27b6ad0e8fd31b45af33edf5a06) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a22fb2a61d52d52be4e93c4c8cac7bbf4) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#adbedaa7eb929f7cea4d3779e73259c9c). * The [`index`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#a38adadd9db08e18e7f80ebf577b9ac4d) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#af758e77b58b6e03cc056f75fc8b4d47d) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a90f6e7c915361b1a2c4d8f401c8a8fcc) of the corresponding learned pattern [when several are learned](learning_process.html.md#easymatch-multiple-models). * A [`draw function`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#a6e7a78511ec2f1348924ca2ea511db22) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#add96a6f4a52d5297f4e6c59bac84a06d) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#ac6d10fe234307aff540065715b6076a1) that optionally draws [`the center`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#a6390b377dff615f6311309fee2af074a) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#af00ada7e6c10cccf64b9a27284d81e58) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#ac670e7b11e6d80a4a2a09f79b1718fc5), [`the bounding box`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#a60ffd76f8f15e07bfa8fca980a2924d5) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a9427c96a20f9839ad005721c22642bfd) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a178b7422f329c3ec41e86c8878244184) and [`the region used for learning`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#af10d895ba6be45c55ae1ea9bcdee5093) [_.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a8061cc4913ddcaf5954204ef3ec90b1a) [_Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a61b6dfc35b24124e48e4e9574fe7af1e) (if there was one). #### HINT To speed up the search process, you can also use [multicore processing](../../advanced_operations/multicore_processing.html.md). This is especially interesting when you use **EasyMatch** with angle and scale tolerances. ## Matching Workflow ## Matching Parameters ### Min/Max Angle * The patterns found in the image can have an angle between [`EMatcher::SetMinAngle`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#afcaaecbe765251da989c67fff90fe5b9) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a2944ac20d4f2d978f4c379a9163a8574) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#afb4f6ed7bd7790700f0329826538e250) and [`EMatcher::SetMaxAngle`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a5ad619139960fafbb9ee13aaf389d928) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#aae4523e58864b586d5520f8b743cb278) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a5d130e77b05453ddf5c148f7541819a7). * 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a05a760ece579ccf52dffd168753ac810) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a89d87f13e7fc353bd25e7ec6151fb8e6) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a4dfd3cbdc4f67db4eb8d68c7d3de2410) and [`EMatcher::SetMaxScale`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a6702c2f494bcb66a3311244674d89046) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a00e6c79f59db55d7778e6bf268957571) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a1ed88ac1c741f2f95c897f3e90b230df). * The anisotropic scale is set by [`EMatcher::SetMinScaleX`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#adddd8535e1941a61e2ed281f3fb71947) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a962d982e945df9fffdbfe0798da7c8ab) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a721192e41d1d81cd4198c0b4602c7b92), [`EMatcher::SetMaxScaleX`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a80f9b3479a81d9c43370e4bba6d293ca) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#ac72cb5934e5729c1ccb55fbd0aa03659) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a9759b6c9845dab12820f3bc2f5f12759), [`EMatcher::SetMinScaleY`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a9615d388a6432aa46fe9cd8ebfeaaed3) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a68075a2e559138c8ca8fd1156667fd8f) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#ac6624afeba335b941abea7c9e85f71e5)and [`EMatcher::SetMaxScaleY`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a082201776e0fd2c01ca1deca9c5ab4f7) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#aecd86be73e124eb37cfd0219b5b1a1fc) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a5c22eaf53c0ca08d5a86bbd23c735272). * 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a3f93c975984fca9a4a508a85e5ba2423) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#abcdd9a9bad024b98e2baac72910327b2) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a29ee01a817e64cccb13d07c1909bfcda) are returned. * At most [`EMatcher::SetMaxPositions`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a91d5e21854a1c5b7c38c72f3cf36c128) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a25c3b43e17b0c17a2f8edaddfcb05978) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a4219c172ba67919eacc094628b54c35b) 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a2142faaa32e306e9c14bbab8322df054) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a873be67d621625fae72aa36fa0bb5e40) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#abd16ee01eb750a7cffb88b3a31f5f6b2) 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#ac4c97be7341241ee12a14b705fb1d150) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a753e5bd7a5a267f3119986f1b5c6235b) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#aa146cdcdcfdb2d330ca60014db506cc1) possesses a timeout: * Use [`EMatcher::SetMatchTimeOut`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a8813043aaabe8d1dee9838964a05343e) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#ad9e5165fbfb4f16f3b20ea6c9f62b0c4) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a205d535dc2e26099df02c6cdbece45dd) to add a time limit to the method [`EMatcher::Match`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#ac4c97be7341241ee12a14b705fb1d150) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a753e5bd7a5a267f3119986f1b5c6235b) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#aa146cdcdcfdb2d330ca60014db506cc1). * 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#abf41de9d423d354526093d7b9eb4dbb4) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a996a8eb126bd1eb1e94b4427afd36754) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#adaf7885e9e0e8b816dfffcfda83ead63) 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#aec6b541e23a197d105822537a8d44cca) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#af0b5c84b1f736641319ce81999463dcd) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a68b4f8170dd33e4ec263118c9514ba77): * By default, [`ECorrelationMode_Normalized`](../../../doxygen_cpp/namespaceeVision.html#ac5f1d84bc2463421b8fd9130567222aeabc86047fbfadf70803499d91a79d81b4) [_.NET](../../../doxygen_cs/namespaceeVision.html#a30d7f6ae56d55acb6f525c1967c8d178) [_Python](../../../doxygen_python/classeVision_1_1ECorrelationMode.html#a03f4f3b70401ea385e351120746d5e4c) 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`](../../../doxygen_cpp/namespaceeVision.html#ac5f1d84bc2463421b8fd9130567222aea470c7f26e20fcc403ad9d2d99aca05e3) [_.NET](../../../doxygen_cs/namespaceeVision.html#a30d7f6ae56d55acb6f525c1967c8d178) [_Python](../../../doxygen_python/classeVision_1_1ECorrelationMode.html#ab14f6219cf3f7dfd48c74a79339ffc55) is sensitive to changes in intensity and contrast. * [`ECorrelationMode_OffsetNormalized`](../../../doxygen_cpp/namespaceeVision.html#ac5f1d84bc2463421b8fd9130567222aeaa01c6de7a443d61f19a65fcc078ca86f) [_.NET](../../../doxygen_cs/namespaceeVision.html#a30d7f6ae56d55acb6f525c1967c8d178) [_Python](../../../doxygen_python/classeVision_1_1ECorrelationMode.html#a679ac8e75f9175594de5d92898ecabc9) is unsensitive to changes in intensity and sensitive to changes in contrast. * [`ECorrelationMode_GainNormalized`](../../../doxygen_cpp/namespaceeVision.html#ac5f1d84bc2463421b8fd9130567222aeaa4e9fb3887cfc913ee6e018d73fb9ded) [_.NET](../../../doxygen_cs/namespaceeVision.html#a30d7f6ae56d55acb6f525c1967c8d178) [_Python](../../../doxygen_python/classeVision_1_1ECorrelationMode.html#a5468f4a582e8f90cd4880a8a69af6323) 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`](../../../doxygen_cpp/classeVision_1_1EGrid.html#a415ea53a1f1822d285b82632df96feb9) [_.NET](../../../doxygen_cs/classeVision_1_1EGrid.html#acd1190e67dcb214bd2c4d23a47885020) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a756d244763c37fd4bd95b3b6fa5ce0ba) 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](learning_process.html.md#easymatch-pyramid-creation) to limit processing time. * By default, these intermediate filtering values are computed from [`EMatcher::SetMaxPositions`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a91d5e21854a1c5b7c38c72f3cf36c128) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a25c3b43e17b0c17a2f8edaddfcb05978) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a4219c172ba67919eacc094628b54c35b) and [`EMatcher::SetMinScore`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a3f93c975984fca9a4a508a85e5ba2423) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#abcdd9a9bad024b98e2baac72910327b2) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a29ee01a817e64cccb13d07c1909bfcda). * If **EasyMatch** does not manage to find (all of) the instances of the pattern in the image, try modifying [`EMatcher::SetMaxInitialPositions`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a4dc4d34764ad3a10ea8467b17c756e38) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a49de071c061e45063db9131f1298e880) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a6638dba13215bbc4d85446bae4f4b247) and/or [`EMatcher::GetInitialMinScore`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a02745674a75bc5ec8bacaca024104930) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#ad9b1ef412928ee93d549a17162bb216e) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a15f5b6cc3deb21bad216631ea3322346). #### Early Candidate Rejection * **EasyMatch** filters out candidates at early stages of the [pyramid](learning_process.html.md#easymatch-pyramid-creation) 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`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a6958133a4d88e9a56486ec0893f61109) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a2a898d1e4b8cb6e04e27d0089c7eb3f5) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a5288e0ba4d3216b2ff2c151894fce447) * You might have to then increase [`EMatcher::SetMaxInitialPositions`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a4dc4d34764ad3a10ea8467b17c756e38) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a49de071c061e45063db9131f1298e880) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a6638dba13215bbc4d85446bae4f4b247) to compensate for the new candidates. #### Final Reduction * Use [`EMatcher::SetFinalReduction`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a8b36ecd62bfeb1ef612d4dad0bae9b79) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#a2f4d7359ecb777bdc5d7c5ed45b92202) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#a59b0fa75dbe4bae2c0f5d4c09265a44f) to stop the iterative position refinement in the [pyramid](learning_process.html.md#easymatch-pyramid-creation) 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](learning_process.html.md#easymatch-pyramid-creation) to achieve sub-pixel accuracy. * If speed is more important than accuracy for your application, you may disable this interpolation with [`EMatcher::SetInterpolate`](../../../doxygen_cpp/classeVision_1_1EMatcher.html#a066fd069ea1ba3129691655ace9533e3) [_.NET](../../../doxygen_cs/classeVision_1_1EMatcher.html#acb203f642ac1a3eb84116d245dcf2ac6) [_Python](../../../doxygen_python/classeVision_1_1EMatcher.html#afd9d66fcd0af6a07b0aef174c99a7ae4).