{"id":28089327,"url":"https://github.com/dennisliu1993/fastest_image_pattern_matching","last_synced_at":"2025-05-13T12:56:34.424Z","repository":{"id":38369193,"uuid":"489012928","full_name":"DennisLiu1993/Fastest_Image_Pattern_Matching","owner":"DennisLiu1993","description":"C++ implementation of a ScienceDirect paper \"An accelerating cpu-based correlation-based image alignment for real-time automatic optical inspection\"","archived":false,"fork":false,"pushed_at":"2025-05-04T01:06:03.000Z","size":118689,"stargazers_count":934,"open_issues_count":42,"forks_count":218,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-05-04T01:24:45.784Z","etag":null,"topics":["image-alignment","image-match","image-recognition","ncc","normalized-cross-correlation","opencv","pattern-finding","pattern-matching","pattern-quick","template-matching"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DennisLiu1993.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-05-05T14:48:17.000Z","updated_at":"2025-05-04T01:06:07.000Z","dependencies_parsed_at":"2025-05-04T01:33:27.049Z","dependency_job_id":null,"html_url":"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DennisLiu1993%2FFastest_Image_Pattern_Matching","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DennisLiu1993%2FFastest_Image_Pattern_Matching/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DennisLiu1993%2FFastest_Image_Pattern_Matching/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DennisLiu1993%2FFastest_Image_Pattern_Matching/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DennisLiu1993","download_url":"https://codeload.github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948338,"owners_count":21988953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-alignment","image-match","image-recognition","ncc","normalized-cross-correlation","opencv","pattern-finding","pattern-matching","pattern-quick","template-matching"],"created_at":"2025-05-13T12:56:33.683Z","updated_at":"2025-05-13T12:56:34.413Z","avatar_url":"https://github.com/DennisLiu1993.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fastest Image Pattern Matching\n## **The best template matching implementation in the world.**\n\nUsing C++/MFC/OpenCV to build a Normalized Cross Corelation-based image alignment algorithm\n\nThe result means the similarity of two images, and the formular is as followed:\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Image/NCC.jpg)\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Image/HighLevel.png)\n\n# New feature: \n1. C++ shared object (.so) with Neon SIMD for **Python** is runnable on Unix (Ventura 13.3) and Linux (Ubuntu Linux 22.04.02) System. \n   Super fast using -O3\n2. C++ .so with Pybind11 for **Python**\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Image/CrossPlatform.png)\n\n# Improvements\n1. rotation invariant, and rotation precision is as high as possible\n2. using image pyrimid as a searching strategy to speed up 4~128 times the original NCC method (depending on template size), minimizing the inspection area on the top level of image pyrimid\n3. optimizing rotation time comsuming from OpenCV by setting needed \"size\" and modifying rotation matrix\n4. **SIMD version of image convolution** (especially useful for large templates)\n   \n   **4.1 update Neon SIMD on MacOS version .so, super fast**\n5. optimizing the function GetNextMaxLoc () with struct s_BlockMax, for special cases whose template sizes are extremely smaller than source sizes, and for large TargetNumber. \n   \n   It gets quite far.\n   \n      Test case: [Src10](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Test%20Images/Src10.bmp) (3648 X 3648) and [Dst10](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Test%20Images/Dst10.jpg) (54 X 54)\n      \n      **Effect: time consuming reduces from 534 ms to 100 ms. speed up 434%**\n\n# In Comparison with commercial libraries\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Test%20Images/Src7.bmp\" alt=\"Inspection Image\" width=\"400\"\u003e\u003cbr\u003e\n      Inspection Image: 4024 X 3036\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Test%20Images/Dst7.bmp\" alt=\"Template Image\" width=\"100\"\u003e\u003cbr\u003e\n      Template Image: 762 X 521\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nLibrary    |Index | Score | Angle | PosX | PosY | Execution Time\n---------  |----- |-------|-------| -----  | -----  |----------------------\nMy Tool    |0     |   1   | 0.046 |1725.857|1045.433| **76ms**  🎖️\nMy Tool    |1     |   0.998   | -119.979 |2662.869|1537.446| \nMy Tool    |2     |  0.991   | 120.150 |1768.936|2098.494| \nCognex     |0     |   1   | 0.030 |1725.960|1045.470| **125ms**\nCognex     |1     |   0.989   | -119.960 |2663.750|1538.040| \nCognex     |2     |  0.983   | 120.090 |1769.250|2099.410| \nAisys    |0     |   1   | 0 |1726.000|1045.500| **202ms**\nAisys    |1     |   0.990   | -119.935 |2663.630|1539.060| \nAisys    |2     |  0.979   | 120.000 |1769.63|2099.780| \n\n**note**: if you want to get a best performance, please make sure you are using release verson (both this project and OpenCV dll). That's because O2-related settings significantly affects efficiency, and the difference of Debug and Release can up to 7 times for some cases.\n\n# Performance Tests (I7-10700)\n**test0** - with user interface\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Image/UIwithResult.jpg)\n\n| Test | Metrics | Image |\n|------|---------|-------|\n| **Test1** | **Execution Time**:\u003cbr\u003e164ms\u003cbr\u003e(80ms with SIMD)\u003cbr\u003e\u003cbr\u003e**Parameters**:\u003cbr\u003e TargetNum=5\u003cbr\u003eOverlap=0.8\u003cbr\u003eScore=0.8\u003cbr\u003eTolerance Angle=180 | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result8.jpg\" alt=\"Test 1 Result\" width=\"800\"\u003e |\n| **Test2** | **Execution Time**:\u003cbr\u003e237ms\u003cbr\u003e(175ms with SIMD) | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result1.jpg\" alt=\"Test 2 Result\" width=\"800\"\u003e |\n| **Test3** | **Execution Time**:\u003cbr\u003e152ms\u003cbr\u003e(100ms with SIMD) | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result2.jpg\" alt=\"Test 3 Result\" width=\"800\"\u003e |\n| **Test4** | **Execution Time**:\u003cbr\u003e21ms\u003cbr\u003e\u003cbr\u003e**Parameters**:\u003cbr\u003eTargetNum=38\u003cbr\u003eScore=0.8\u003cbr\u003eTolerance Angle=0\u003cbr\u003eMin Reduced Area=256 | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result3.jpg\" alt=\"Test 4 Result\" width=\"800\"\u003e |\n| **Test5** | **Execution Time**:\u003cbr\u003e27ms | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result4.jpg\" alt=\"Test 5 Result\" width=\"800\"\u003e |\n| **Test6** | **Execution Time**:\u003cbr\u003e1157ms\u003cbr\u003e(657ms with SIMD)\u003cbr\u003e\u003cbr\u003e**Parameters**:\u003cbr\u003eTargetNum=15\u003cbr\u003eScore=0.8\u003cbr\u003eTolerance Angle=180\u003cbr\u003eMin Reduced Area=256 | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result6.jpg\" alt=\"Test 6 Result\" width=\"800\"\u003e |\n| **Test7** | **Execution Time**:\u003cbr\u003e18ms\u003cbr\u003e\u003cbr\u003e**Parameters**:\u003cbr\u003eTargetNum=100\u003cbr\u003eScore=0.5\u003cbr\u003eTolerance Angle=0\u003cbr\u003eMaxOverlap=0.5\u003cbr\u003eMin Reduced Area=1024 | \u003cimg src=\"https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Result%20Images/Result9.jpg\" alt=\"Test 7 Result\" width=\"800\"\u003e |\n\n# Steps to build this project\n1.\tDownload Visual Studio 2017 or newer versions\n2.\tCheck on the option of \"x86 and x64 version of C++ MFC\"\n3.\tInstall\n4.\tOpen MatchTool.vcxproj\n5.\tUpgrade if it is required\n6.\tOpen this project's property page\n7.\tModified \"General-Output Directory\" to the .exe directory you want (usually the directory where your opencv_worldXX.dll locates)\n8.\tChoose the SDK version you have in \"General-Windows SDK Version\"\n9.\tChoose the right toolset you have in \"General-Platform Toolset\" (for me, it is Visual Studio 2017 (v141))\n10.\tGo to \"VC++ Directories\", and type in \"Include Directories\" for your own OpenCV (e.g. C:\\OpenCV3.1\\opencv\\build\\include or C:\\OpenCV4.0\\opencv\\build\\include)\n11.\tType in \"Library Directories\" for your own OpenCV's library path (the directory where your opencv_worldXX.lib locates)\n12.\tGo to \"Linker-Input\", and type in library name (e.g. opencv_world310d_vs2017.lib or opencv_world401d.lib)\n13.\tMake sure that your opencv_worldXX.dll and MatchTool.Lang are in the same directory as .exe of this project\n\n# Adaptation for OpenCV4.X\n1.Select Debug_4.X or Release_4.X in \"Solution Configuration\"\n![image](https://user-images.githubusercontent.com/104763587/169198235-f023ba0f-2039-4f00-8816-d270f7c03575.png)\n\n2.Do step 10~12 in previous section\n\n# Usage of this project\n1.\tSelect the Language you want\n2.\tDrag Source Image to the Left Area\n3.\tDrag Dst Image to the Right Top Area\n4.\tPush \"Execute Button\"\n\n# Parameters Setting\n1. **Target Number**: possible max objects you want to find in the inspection image\n2. **Max OverLap Ratio**: (the overlap area between two findings) / area of golden sample\n3. **Score (Similarity)**: accepted similarity of findings (0~1), lower score causes more execution time\n4. **Tolerance Angle**: possible rotation of targets in the inspection image (180 means search range is from -180~180), higher angle causes more execution time\n      or you can push \"↓\" button to select 2 angle range\n5. **Min Reduced Area**: the min area of toppest level in image pyrimid (trainning stage)\n\n# About outputs\n1. results are sorted by score (decreasing order)\n2. Angles: inspected rotation of findings\n3. PosX, PosY: pixel position of findings\n\n# Demonstration Video\n[youtube link](https://www.youtube.com/watch?v=2h_lN79SpMM)\n\n![Image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Gif/Fastest%20implement%20of%20Image%20Pattern%20Matching%20with%20arbitrary%20rotation%20using%20OpenCV.%E5%9F%BA%E6%96%BCOpenCV%E7%9A%84%E8%B6%85%E5%BF%AB%E9%80%9F%E5%9C%96%E5%83%8F%E5%AE%9A%E4%BD%8D%E6%BC%94%E7%AE%97%E6%B3%95.gif)\n\n# This project can also be used as Optical Character Recognition (OCR)\n[youtube link](https://www.youtube.com/watch?v=lM0NK6xVNfg)\n\n\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Gif/NCCBasedOCR.gif)\n\n# Special Items \ncontact information: dennisliu1993@gmail.com\n1. C++ shared library (.so) for python (Unix-ARM64, Ubuntu 22.04.02-ARM64)\n2. C++/MFC dll for .Net framework (Windows)\n3. pure C++ dll for Python (Windows)\n4. pybind11 .so\n\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Gif/macFPM.gif)\n![image](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Manual%20Gif/FPMLib_for_Python.gif)\n\n# Reference Papers\n1. [Template Matching using Fast Normalized Cross Correlation](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/Template%20Matching%20using%20Fast%20Normalized%20Cross%20Correlation.pdf)\n2. [computers_and_electrical_engineering_an_accelerating_cpu_based_correlation-based_image_alignment](https://github.com/DennisLiu1993/Fastest_Image_Pattern_Matching/blob/main/computers_and_electrical_engineering_an_accelerating_cpu_based_correlation-based_image_alignment.pdf)\n\n# Special Note:\n\nIf you encounter an error(exception) on the constructor of opencv class \"RotatedRect\", modify the content in `types.cpp`:\nthis might due to Windows updates\n\n```cpp\nRotatedRect::RotatedRect(const Point2f\u0026 _point1, const Point2f\u0026 _point2, const Point2f\u0026 _point3)\n{\n    Point2f _center = 0.5f * (_point1 + _point3);\n    Vec2f vecs[2];\n    vecs[0] = Vec2f(_point1 - _point2);\n    vecs[1] = Vec2f(_point2 - _point3);\n    double x = std::max(norm(_point1), std::max(norm(_point2), norm(_point3)));\n    double a = std::min(norm(vecs[0]), norm(vecs[1]));\n    // check that given sides are perpendicular\n    // this is the line you need to modify\n    CV_Assert( std::fabs(vecs[0].ddot(vecs[1])) * a \u003c= FLT_EPSILON * 9 * x * (norm(vecs[0]) * norm(vecs[1])) );\n\n    // wd_i stores which vector (0,1) or (1,2) will make the width\n    // One of them will definitely have slope within -1 to 1\n    int wd_i = 0;\n    if( std::fabs(vecs[1][1]) \u003c std::fabs(vecs[1][0]) ) wd_i = 1;\n    int ht_i = (wd_i + 1) % 2;\n\n    float _angle = std::atan(vecs[wd_i][1] / vecs[wd_i][0]) * 180.0f / (float) CV_PI;\n    float _width = (float) norm(vecs[wd_i]);\n    float _height = (float) norm(vecs[ht_i]);\n\n    center = _center;\n    size = Size2f(_width, _height);\n    angle = _angle;\n}\n```\n\nmodify threshold value of **CV_Assert line** to a bigger one\n\nthen recompile the source code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdennisliu1993%2Ffastest_image_pattern_matching","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdennisliu1993%2Ffastest_image_pattern_matching","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdennisliu1993%2Ffastest_image_pattern_matching/lists"}