# Find Matches * Once a pattern is learned, it can be found in an image by calling [`EPatternFinder::Find`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#aeeb160cde9343ffc0d8583ac1d330e4d) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a9c35c544243729d9907eb708f7d2a0e2) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a44780e599d160cbb5f8e405042ace771). * 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 [Contrast 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), [`Scale`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#ab81538c8ddd888d41888721f099f918d) [.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#ab93c3224cac8f61664f4c697c3fce6a7) [Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#aad32e97444da721ce9948d477e1895a6) 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.html.md#learn-multiple). * 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 feature points`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#ac823d50a618bd0a00521526bf1f2c422) [.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a55ab094961805a99833330560a61f87c) [Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a63e7d8f6d9ee6f38e0a7df100c1744bc), [`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 **EasyFind** with angle and scale tolerances. ## Find Parameters The following parameters are set and used in the process find process. ### Maximum Number of expected Instances Use the parameter [`EPatternFinder::SetMaxInstances`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#ae0f84f9bf2baf3358e5d7a40afe3d255) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a6ca9eab2cc0d6d7cf3ab33e31a7aa0b9) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#ae28bc008276032b20f3d1623be1ee7b5) to set the maximum number of instances that **EasyFind** returns. ![image](assets/images/easyfind/finding_param_illu_max_nbr_of_inst.webp) ### Contrast Mode **EasyFind** ranks potential matches based on a score. The score used depends on the [`EFindContrastMode`](../../../doxygen_cpp/namespaceeVision.html#af5522ee465f7c7905863bcabcab13ff5) [.NET](../../../doxygen_cs/namespaceeVision.html#ab1144cfc933e014bb34f679dbf27404e) [Python](../../../doxygen_python/classeVision_1_1EFindContrastMode.html). The contrast mode, may be: * `Normal`: the score is normalized between `-1` and `1`: - `1` means a perfect match with the same contrast as the pattern. - `0` means no match. - `-1` means a perfect match but with the inverted contrast compared to the pattern. * `Inverse`: the score is normalized between `-1` and `1`: - `1` means a perfect match with the inverted contrast compared to the pattern. - `0` means no match. - `-1` means a perfect match but with the same contrast as the pattern. * `Any`: the score is normalized between `0` and `1`: - `1` means a perfect match with the same contrast or the inverted contrast compared to the pattern. - `0` means no match. By default, the score is computed as the normalized sum of the correlation of each feature point. * The feature points with a high gradient have more weight. * Incomplete instances get a relatively high score. In addition, a `Point by point` variant also exists. In that case, the score is computed as the mean of the normalized correlation of each feature point. * Each feature point has the same weight. * Images with irregular lighting and instances with variable contrast get a relatively high score. * To use `Point by point` variant, add `PointByPoint` to the name of the enum, i.e. `EFindContrastMode_PointByPointNormal` instead of `EFindContrastMode_Normal`. Use the parameter [`EPatternFinder::SetContrastMode`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a5888043fff60ebc9af62de48a0c9c696) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a1b8fe88855ec4d71515c145bbb2e41aa) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#aebefdd8a5b5177a8b70f19fddd03eaee) to select the contrast mode. The default value is [`EFindContrastMode_Normal`](../../../doxygen_cpp/namespaceeVision.html#af5522ee465f7c7905863bcabcab13ff5a92de591917d1d27bdaf7ddc7768640d4) [.NET](../../../doxygen_cs/namespaceeVision.html#ab1144cfc933e014bb34f679dbf27404e) [Python](../../../doxygen_python/classeVision_1_1EFindContrastMode.html#ad45e21491aaefbc146e05458395c2b16). ### Minimum Score The score depends on the [`EFindContrastMode`](../../../doxygen_cpp/namespaceeVision.html#af5522ee465f7c7905863bcabcab13ff5) [.NET](../../../doxygen_cs/namespaceeVision.html#ab1144cfc933e014bb34f679dbf27404e) [Python](../../../doxygen_python/classeVision_1_1EFindContrastMode.html), see [above](). Use the parameter [`EPatternFinder::SetMinScore`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#abb78103d2c5783dbf5ed35b37995b4c0) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#ab8779a92ce47e094ae9ecaad78314fef) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a00869a8fbc8ba4b7e5e203637be3fe46) to set the minimum score for an instance to be accepted and returned. The default value is `-1.0` (no score filtering). ### Angle and Scale The angle and scale ranges are defined by a bias and a tolerance: * For example, with an angle bias of 20° and an angle tolerance of 5°, **EasyFind** returns instances with an angle between 15° and 25° with respect to the learned pattern (20° ± 5°). * The default values are `1.0` for the scale bias and `0.0` for the other parameters. That means **EasyFind** returns only patterns with no rotation nor scaling. * Use the parameters [`EPatternFinder::SetAngleBias`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a24d54b8c4c3fca419a1d52e504446e5b) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#af46c05d09b5cb11c9e8e89201a6b4009) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a3968fb6c9f7602c70c28b8615c059c20) and [`EPatternFinder::SetAngleTolerance`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#abf2d49d8a396316e3f242b3f2788e6f6) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a8c22d75a3952b35b8ce4a8105e319e0f) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a6c4d178e7fe69a4b1397f053abcc89e7) to set the angle range. * Use the parameters [`EPatternFinder::SetScaleBias`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a99d5ba7dede956f345bec5269fe112c6) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#acb3d42efa918e9a600538307549cb938) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a93835395a5e8888133b9f87a4948c311) and [`EPatternFinder::SetScaleTolerance`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a418836f620e9db0d16578abae2536a40) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a64117a08ea1c0aa129f00bab851629f3) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a07b721ac27ead94d778f844e3b12e0a0) to set the scale range. ![image](assets/images/easyfind/finding_param_illu_angle_and_scale.webp) ### Compute Per-Feature-Point Score Use [`EPatternFinder::SetComputePerFeaturePointScore`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a809ff436af860f8905a4cc795e09d06e) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a3eecff6054b130b8b5d5931394f09585) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#af2b30781e77e140289831b47c02eef40) to compute a score for each feature point. * This allows to inspect graphically, for each feature point, if it has a high (green), middle (yellow) or poor (red) score. * Drawing the feature points can help to detect occlusions, small scale, angle or mechanical differences between pattern and image and differences between subsets of the pattern and the image (that might be worth filtering out with an `ERegion`). * Note that the “bad” feature points are not necessarily those with a small score if the found position isn’t exactly right. * The feature points scores are drawn with [`EFoundPattern::Draw()`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#a6e7a78511ec2f1348924ca2ea511db22) [.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#add96a6f4a52d5297f4e6c59bac84a06d) [Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#ac6d10fe234307aff540065715b6076a1) if [`EPatternFinder::SetComputePerFeaturePointScore()`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a809ff436af860f8905a4cc795e09d06e) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a3eecff6054b130b8b5d5931394f09585) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#af2b30781e77e140289831b47c02eef40) and [`EFoundPattern::SetDrawFeaturePoints()`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html#ac823d50a618bd0a00521526bf1f2c422) [.NET](../../../doxygen_cs/classeVision_1_1EFoundPattern.html#a55ab094961805a99833330560a61f87c) [Python](../../../doxygen_python/classeVision_1_1EFoundPattern.html#a63e7d8f6d9ee6f38e0a7df100c1744bc) are set to true. ![](assets/images/easyfind/per_fp_score_occlusion.webp)![](assets/images/easyfind/per_fp_score_too_small.webp)![](assets/images/easyfind/per_fp_score_good_size.webp)![](assets/images/easyfind/per_fp_score_no_region.webp)![](assets/images/easyfind/per_fp_score_region.webp) ### Timeout [`EPatternFinder::Find`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#aeeb160cde9343ffc0d8583ac1d330e4d) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a9c35c544243729d9907eb708f7d2a0e2) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a44780e599d160cbb5f8e405042ace771) possesses a timeout: * Use [`EPatternFinder::SetFindTimeOut`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#ae545b8a1f7da3628f4c16a0a0156b823) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#ac6bd2b8ac6bdc3cfb6cb7e472d6a1423) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#abc735e472e4ba3a6288cecad03acd394) to add a time limit to the method [`EPatternFinder::Find`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#aeeb160cde9343ffc0d8583ac1d330e4d) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a9c35c544243729d9907eb708f7d2a0e2) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a44780e599d160cbb5f8e405042ace771). * 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 #### Maximum Overlap **EasyFind** can filter out instances that completely or partially overlap with each other. Use the parameter [`EPatternFinder::SetMaxOverlap`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a28c016d77c11c4095ef97a73755f4560) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a5c8828c102f1d9017749f00710ec4e89) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#ad33444d47082add14c149507570cf9bd) to define the allowed overlap. - The maximum overlap is defined as the area of both instances intersection divided by the area of the smallest instance. - Set the parameter between `0.0` (no overlap allowed) and `1.0` (complete overlap allowed). - The default value is `1.0` (complete overlap allowed). - The instance with biggest score is kept and the one with smallest score discarded. ![image](assets/images/easyfind/finding_param_illu_max_overlap.webp) #### Find Partial Patterns Use the parameter [`EPatternFinder::SetFindExtension`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a12d561e9dfd13dc4a765e22f139f0d3a) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#ab524b62e1b4c9948b26b2409f610b0bd) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a7e7cdf0fee8d256c43ecbd74b65c36d9) to extend the search area (in pixels) and locate instances of thin structures and consistent edges that are partially out of the search field. ![image](assets/images/easyfind/finding_param_illu_find_extension.webp) #### Local Search Mode #### NOTE In the multistage approach: * At the coarsest stage, **EasyFind** finds the pattern occurrence candidates. * At each of the following stages, their position and score are refined until the last and finest one. This refining is achieved by searching for better candidates in the neighborhood of each of the ones found in the previous stage. Use the parameter [`EPatternFinder::SetLocalSearchMode`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#ae23afd6530bc347830e5a94c77fb92aa) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#ad218219cad5b0ae904b728da973e00d0) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#ae1bda6226a3bcdaff7fd13053833cbcc) to set the extent of the neighborhood in which the better candidates are searched. - [`ELocalSearchMode_Basic`](../../../doxygen_cpp/namespaceeVision.html#adf3831301916855aba2053866ca53281aba12cd078d4b0bb2f0a9b2b08cace21b) [.NET](../../../doxygen_cs/namespaceeVision.html#a80b0ee6c036b917e08276c35eb02b20b) [Python](../../../doxygen_python/classeVision_1_1ELocalSearchMode.html#a175267945ce3cfca06ab8297122d77d9): the default local search neighborhood Search scope: `Angle = Scale = X = Y = 3` - [`ELocalSearchMode_ExtendedTranslation`](../../../doxygen_cpp/namespaceeVision.html#adf3831301916855aba2053866ca53281aa92c501a92ac1dd72289eb8d80edfe2b) [.NET](../../../doxygen_cs/namespaceeVision.html#a80b0ee6c036b917e08276c35eb02b20b) [Python](../../../doxygen_python/classeVision_1_1ELocalSearchMode.html#ab8853d959330cd972525608c8e62d2f0): the local search neighborhood is extended along the translation degrees of freedom. Search scope: `Angle = Scale = 3`; `X = Y = 5` - [`ELocalSearchMode_ExtendedAll`](../../../doxygen_cpp/namespaceeVision.html#adf3831301916855aba2053866ca53281a1aabe323b0ab79133d378ed75bf6f9aa) [.NET](../../../doxygen_cs/namespaceeVision.html#a80b0ee6c036b917e08276c35eb02b20b) [Python](../../../doxygen_python/classeVision_1_1ELocalSearchMode.html#a9661ce4dc6f9ef076002c5f5f78d3021): the local search neighborhood is extended along all the degrees of freedom. Search scope: `Angle = Scale = X = Y = 5` - [`ELocalSearchMode_ExtendedMore`](../../../doxygen_cpp/namespaceeVision.html#adf3831301916855aba2053866ca53281a4053755808f9ff63e725699e72e0d47e) [.NET](../../../doxygen_cs/namespaceeVision.html#a80b0ee6c036b917e08276c35eb02b20b) [Python](../../../doxygen_python/classeVision_1_1ELocalSearchMode.html#aeede2752e403336f63ea14c7721935ce): same as [`ELocalSearchMode_ExtendedAll`](../../../doxygen_cpp/namespaceeVision.html#adf3831301916855aba2053866ca53281a1aabe323b0ab79133d378ed75bf6f9aa) [.NET](../../../doxygen_cs/namespaceeVision.html#a80b0ee6c036b917e08276c35eb02b20b) [Python](../../../doxygen_python/classeVision_1_1ELocalSearchMode.html#a9661ce4dc6f9ef076002c5f5f78d3021) but with a larger extension. Search scope: `Angle = Scale = 7`; `X = Y = 9` - [`ELocalSearchMode_Custom`](../../../doxygen_cpp/namespaceeVision.html#adf3831301916855aba2053866ca53281a00b66b4e097aaf33a762291deb09e6e6) [.NET](../../../doxygen_cs/namespaceeVision.html#a80b0ee6c036b917e08276c35eb02b20b) [Python](../../../doxygen_python/classeVision_1_1ELocalSearchMode.html#af271e4db8ad1aa6e531e7f71f3289bc7): manually define the search scope: - Use [`EPatternFinder::SetAngleSearchExtent`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a16f08e3de08b7875a7e23b5862f32097) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a6683c46dd879048dabf127a09bf4a185) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#ada79b1550fdd34823753f4281524db71) to set the `Angle` and [`EPatternFinder::SetScaleSearchExtent`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a8037c28451d65656574a802f3602aee8) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a69614e0791b9aff81a3dbabf3009bfb9) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a1b2ffc659bc67d676f7993941e52219a) to set the `Scale` - Use [`EPatternFinder::SetXSearchExtent`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#aaf224e85a6b6b864b1dcbfbd9f92c2c6) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a86cba7cf8efe3ba9c1256b770cd269ec) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a4750f9dcf627291782165948973ac197) and [`EPatternFinder::SetYSearchExtent`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#af288590b6dbb9c052812bf91796387b0) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#add86175c816b844287eae39d89ab7be2) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a7bd33e11ada81a37d86cca81802352a6) to set the translation along `X` and `Y` #### Maximum Initial Candidates #### NOTE During the search for matching patterns, **EasyFind** considers a set of candidates and progressively refines it: * A large number of initial candidates can enable finding difficult or partial matches but at the cost of increasing the processing time. * A small number of initial candidates can speed up the find process. Use the parameter [`EPatternFinder::SetMaxInitialCandidates`](../../../doxygen_cpp/classeVision_1_1EPatternFinder.html#a28f59d400eda984784d4af1bb1ef80c9) [.NET](../../../doxygen_cs/classeVision_1_1EPatternFinder.html#a8f4b195eacacd94f3c26454b5d05d859) [Python](../../../doxygen_python/classeVision_1_1EPatternFinder.html#a37c4d23be67e3321e20cf8067d5d7468) to set the maximum number of initial candidates that **EasyFind** considers. - This number must be greater than or equal to the number of instances to be found. - By default, the value is chosen internally.