{"id":13477159,"url":"https://github.com/PyImageSearch/imutils","last_synced_at":"2025-03-27T04:32:38.470Z","repository":{"id":25668314,"uuid":"29104125","full_name":"PyImageSearch/imutils","owner":"PyImageSearch","description":"A series of convenience functions to make basic image processing operations such as translation, rotation, resizing, skeletonization, and displaying Matplotlib images easier with OpenCV and Python.","archived":false,"fork":false,"pushed_at":"2024-06-24T13:34:47.000Z","size":7046,"stargazers_count":4534,"open_issues_count":162,"forks_count":1024,"subscribers_count":152,"default_branch":"master","last_synced_at":"2024-10-29T15:33:07.944Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PyImageSearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2015-01-11T20:05:39.000Z","updated_at":"2024-10-29T14:28:32.000Z","dependencies_parsed_at":"2024-06-18T11:02:07.746Z","dependency_job_id":"adb6defd-1940-4ed1-9bb6-2d522f6e202b","html_url":"https://github.com/PyImageSearch/imutils","commit_stats":{"total_commits":107,"total_committers":22,"mean_commits":4.863636363636363,"dds":0.485981308411215,"last_synced_commit":"9f740a53bcc2ed7eba2558afed8b4c17fd8a1d4c"},"previous_names":["jrosebr1/imutils"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyImageSearch%2Fimutils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyImageSearch%2Fimutils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyImageSearch%2Fimutils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyImageSearch%2Fimutils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PyImageSearch","download_url":"https://codeload.github.com/PyImageSearch/imutils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245568567,"owners_count":20636803,"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":[],"created_at":"2024-07-31T16:01:38.910Z","updated_at":"2025-03-27T04:32:38.463Z","avatar_url":"https://github.com/PyImageSearch.png","language":"Python","readme":"# imutils\nA series of convenience functions to make basic image processing functions such as translation, rotation, resizing, skeletonization, and displaying Matplotlib images easier with OpenCV and ***both*** Python 2.7 and Python 3.\n\nFor more information, along with a detailed code review check out the following posts on the [PyImageSearch.com](http://www.pyimagesearch.com) blog:\n\n- [http://www.pyimagesearch.com/2015/02/02/just-open-sourced-personal-imutils-package-series-opencv-convenience-functions/](http://www.pyimagesearch.com/2015/02/02/just-open-sourced-personal-imutils-package-series-opencv-convenience-functions/)\n- [http://www.pyimagesearch.com/2015/03/02/convert-url-to-image-with-python-and-opencv/](http://www.pyimagesearch.com/2015/03/02/convert-url-to-image-with-python-and-opencv/)\n- [http://www.pyimagesearch.com/2015/04/06/zero-parameter-automatic-canny-edge-detection-with-python-and-opencv/](http://www.pyimagesearch.com/2015/04/06/zero-parameter-automatic-canny-edge-detection-with-python-and-opencv/)\n- [http://www.pyimagesearch.com/2014/09/01/build-kick-ass-mobile-document-scanner-just-5-minutes/](http://www.pyimagesearch.com/2014/09/01/build-kick-ass-mobile-document-scanner-just-5-minutes/)\n- [http://www.pyimagesearch.com/2015/08/10/checking-your-opencv-version-using-python/](http://www.pyimagesearch.com/2015/08/10/checking-your-opencv-version-using-python/)\n\n## Installation\nProvided you already have NumPy, SciPy, Matplotlib, and OpenCV already installed, the `imutils` package is completely `pip`-installable:\n\n\u003cpre\u003e$ pip install imutils\u003c/pre\u003e\n\n## Finding function OpenCV functions by name\nOpenCV can be a big, hard to navigate library, especially if you are just getting started learning computer vision and image processing. The `find_function` method allows you to quickly search function names across modules (and optionally sub-modules) to find the function you are looking for.\n\n#### Example:\nLet's find all function names that contain the text `contour`:\n\n\u003cpre\u003eimport imutils\nimutils.find_function(\"contour\")\u003c/pre\u003e\n\n#### Output:\n\u003cpre\u003e1. contourArea\n2. drawContours\n3. findContours\n4. isContourConvex\u003c/pre\u003e\n\nThe `contourArea` function could therefore be accessed via: `cv2.contourArea`\n\n\n## Translation\nTranslation is the shifting of an image in either the *x* or *y* direction. To translate an image in OpenCV you would need to supply the *(x, y)*-shift, denoted as *(t\u003csub\u003ex\u003c/sub\u003e, t\u003csub\u003ey\u003c/sub\u003e)* to construct the translation matrix *M*:\n\n![Translation equation](docs/images/translation_eq.png?raw=true)\n\nAnd from there, you would need to apply the `cv2.warpAffine` function.\n\nInstead of manually constructing the translation matrix *M* and calling `cv2.warpAffine`, you can simply make a call to the `translate` function of `imutils`.\n\n#### Example:\n\u003cpre\u003e# translate the image x=25 pixels to the right and y=75 pixels up\ntranslated = imutils.translate(workspace, 25, -75)\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/translation.png?raw=true\" alt=\"Translation example\" style=\"max-width: 500px;\"\u003e\n\n## Rotation\nRotating an image in OpenCV is accomplished by making a call to `cv2.getRotationMatrix2D` and `cv2.warpAffine`. Further care has to be taken to supply the *(x, y)*-coordinate of the point the image is to be rotated about. These calculation calls can quickly add up and make your code bulky and less readable. The `rotate` function in `imutils` helps resolve this problem.\n\n#### Example:\n\u003cpre\u003e# loop over the angles to rotate the image\nfor angle in xrange(0, 360, 90):\n\t# rotate the image and display it\n\trotated = imutils.rotate(bridge, angle=angle)\n\tcv2.imshow(\"Angle=%d\" % (angle), rotated)\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/rotation.png?raw=true\" alt=\"Rotation example\" style=\"max-width: 500px;\"\u003e\n\n## Resizing\nResizing an image in OpenCV is accomplished by calling the `cv2.resize` function. However, special care needs to be taken to ensure that the aspect ratio is maintained.  This `resize` function of `imutils` maintains the aspect ratio and provides the keyword arguments `width` and `height` so the image can be resized to the intended width/height while (1) maintaining aspect ratio and (2) ensuring the dimensions of the image do not have to be explicitly computed by the developer.\n\nAnother optional keyword argument, `inter`, can be used to specify interpolation method as well.\n\n#### Example:\n\u003cpre\u003e# loop over varying widths to resize the image to\nfor width in (400, 300, 200, 100):\n\t# resize the image and display it\n\tresized = imutils.resize(workspace, width=width)\n\tcv2.imshow(\"Width=%dpx\" % (width), resized)\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/resizing.png?raw=true\" alt=\"Resizing example\" style=\"max-width: 500px;\"\u003e\n\n## Skeletonization\nSkeletonization is the process of constructing the \"topological skeleton\" of an object in an image, where the object is presumed to be white on a black background. OpenCV does not provide a function to explicitly construct the skeleton, but does provide the morphological and binary functions to do so.\n\nFor convenience, the `skeletonize` function of `imutils` can be used to construct the topological skeleton of the image.\n\nThe first argument, `size` is the size of the structuring element kernel. An optional argument, `structuring`, can be used to control the structuring element -- it defaults to `cv2.MORPH_RECT`\t, but can be any valid structuring element.\n\n#### Example:\n\u003cpre\u003e# skeletonize the image\ngray = cv2.cvtColor(logo, cv2.COLOR_BGR2GRAY)\nskeleton = imutils.skeletonize(gray, size=(3, 3))\ncv2.imshow(\"Skeleton\", skeleton)\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/skeletonization.png?raw=true\" alt=\"Skeletonization example\" style=\"max-width: 500px;\"\u003e\n\n## Displaying with Matplotlib\nIn the Python bindings of OpenCV, images are represented as NumPy arrays in BGR order. This works fine when using the `cv2.imshow` function. However, if you intend on using Matplotlib, the `plt.imshow` function assumes the image is in RGB order. A simple call to `cv2.cvtColor` will resolve this problem, or you can use the `opencv2matplotlib` convenience function.\n\n#### Example:\n\u003cpre\u003e# INCORRECT: show the image without converting color spaces\nplt.figure(\"Incorrect\")\nplt.imshow(cactus)\n\n# CORRECT: convert color spaces before using plt.imshow\nplt.figure(\"Correct\")\nplt.imshow(imutils.opencv2matplotlib(cactus))\nplt.show()\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/matplotlib.png?raw=true\" alt=\"Matplotlib example\" style=\"max-width: 500px;\"\u003e\n\n## URL to Image\nThis the `url_to_image` function accepts a single parameter: the `url` of the image we want to download and convert to a NumPy array in OpenCV format. This function performs the download in-memory. The `url_to_image` function has been detailed [here](http://www.pyimagesearch.com/2015/03/02/convert-url-to-image-with-python-and-opencv/) on the PyImageSearch blog.\n\n#### Example:\n\u003cpre\u003eurl = \"http://pyimagesearch.com/static/pyimagesearch_logo_github.png\"\nlogo = imutils.url_to_image(url)\ncv2.imshow(\"URL to Image\", logo)\ncv2.waitKey(0)\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/url_to_image.png?raw=true\" alt=\"Matplotlib example\" style=\"max-width: 500px;\"\u003e\n\n## Checking OpenCV Versions\nOpenCV 3 has finally been released! But with the major release becomes backward compatibility issues (such as with the `cv2.findContours` and `cv2.normalize` functions). If you want your OpenCV 3 code to be backwards compatible with OpenCV 2.4.X, you'll need to take special care to check which version of OpenCV is currently being used and then take appropriate action. The `is_cv2()` and `is_cv3()` are simple functions that can be used to automatically determine the OpenCV version of the current environment.\n\n#### Example:\n\u003cpre\u003eprint(\"Your OpenCV version: {}\".format(cv2.__version__))\nprint(\"Are you using OpenCV 2.X? {}\".format(imutils.is_cv2()))\nprint(\"Are you using OpenCV 3.X? {}\".format(imutils.is_cv3()))\u003c/pre\u003e\n\n#### Output:\n\u003cpre\u003eYour OpenCV version: 3.0.0\nAre you using OpenCV 2.X? False\nAre you using OpenCV 3.X? True\u003c/pre\u003e\n\n## Automatic Canny Edge Detection\nThe Canny edge detector requires two parameters when performing hysteresis. However, tuning these two parameters to obtain an optimal edge map is non-trivial, especially when working with a dataset of images. Instead, we can use the `auto_canny` function which uses the median of the grayscale pixel intensities to derive the upper and lower thresholds. You can read more about the `auto_canny` function [here](http://www.pyimagesearch.com/2015/04/06/zero-parameter-automatic-canny-edge-detection-with-python-and-opencv/).\n\n#### Example:\n\u003cpre\u003egray = cv2.cvtColor(logo, cv2.COLOR_BGR2GRAY)\nedgeMap = imutils.auto_canny(gray)\ncv2.imshow(\"Original\", logo)\ncv2.imshow(\"Automatic Edge Map\", edgeMap)\u003c/pre\u003e\n\n#### Output:\n\n\u003cimg src=\"docs/images/auto_canny.png?raw=true\" alt=\"Matplotlib example\" style=\"max-width: 500px;\"\u003e\n\n## 4-point Perspective Transform\nA common task in computer vision and image processing is to perform a 4-point perspective transform of a ROI in an image and obtain a top-down, \"birds eye view\" of the ROI. The `perspective` module takes care of this for you. A real-world example of applying a 4-point perspective transform can be bound in this blog on on [building a kick-ass mobile document scanner](http://www.pyimagesearch.com/2014/09/01/build-kick-ass-mobile-document-scanner-just-5-minutes/).\n\n#### Example\nSee the contents of `demos/perspective_transform.py`\n\n#### Output:\n\n\u003cimg src=\"docs/images/perspective_transform.png?raw=true\" alt=\"Matplotlib example\" style=\"max-width: 500px;\"\u003e\n\n## Sorting Contours\nThe contours returned from `cv2.findContours` are unsorted. By using the `contours` module the the `sort_contours` function we can sort a list of contours from left-to-right, right-to-left, top-to-bottom, and bottom-to-top, respectively.\n\n#### Example:\nSee the contents of `demos/sorting_contours.py`\n\n#### Output:\n\n\u003cimg src=\"docs/images/sorting_contours.png?raw=true\" alt=\"Matplotlib example\" style=\"max-width: 500px;\"\u003e\n\n## (Recursively) Listing Paths to Images\nThe `paths` sub-module of `imutils` includes a function to recursively find images based on a root directory.\n\n#### Example:\nAssuming we are in the `demos` directory, let's list the contents of the `../demo_images`:\n\n\u003cpre\u003efrom imutils import paths\nfor imagePath in paths.list_images(\"../demo_images\"):\n\tprint imagePath\u003c/pre\u003e\n\n#### Output:\n\u003cpre\u003e../demo_images/bridge.jpg\n../demo_images/cactus.jpg\n../demo_images/notecard.png\n../demo_images/pyimagesearch_logo.jpg\n../demo_images/shapes.png\n../demo_images/workspace.jpg\u003c/pre\u003e\n","funding_links":[],"categories":["Python","Data Processing","Python Libraries","图像数据与CV","🛸 Other"],"sub_categories":["Data Pre-processing \u0026 Loading","🛠️ Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPyImageSearch%2Fimutils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPyImageSearch%2Fimutils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPyImageSearch%2Fimutils/lists"}