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.

Adrian Rosebrock

Last update: Jan 8, 2023

Related tags

Deep Learning imutils

Overview

imutils

A 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.

For more information, along with a detailed code review check out the following posts on the PyImageSearch.com blog:

Installation

Provided you already have NumPy, SciPy, Matplotlib, and OpenCV already installed, the imutils package is completely pip-installable:

$ pip install imutils

Finding function OpenCV functions by name

OpenCV 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.

Example:

Let's find all function names that contain the text contour:

import imutils
imutils.find_function("contour")

Output:

1. contourArea
2. drawContours
3. findContours
4. isContourConvex

The contourArea function could therefore be accessed via: cv2.contourArea

Translation

Translation 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_x, t_y) to construct the translation matrix M:

And from there, you would need to apply the cv2.warpAffine function.

Instead of manually constructing the translation matrix M and calling cv2.warpAffine, you can simply make a call to the translate function of imutils.

Example:

# translate the image x=25 pixels to the right and y=75 pixels up
translated = imutils.translate(workspace, 25, -75)

Output:

Rotation

Rotating 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.

Example:

# loop over the angles to rotate the image
for angle in xrange(0, 360, 90):
	# rotate the image and display it
	rotated = imutils.rotate(bridge, angle=angle)
	cv2.imshow("Angle=%d" % (angle), rotated)

Output:

Resizing

Resizing 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.

Another optional keyword argument, inter, can be used to specify interpolation method as well.

Example:

# loop over varying widths to resize the image to
for width in (400, 300, 200, 100):
	# resize the image and display it
	resized = imutils.resize(workspace, width=width)
	cv2.imshow("Width=%dpx" % (width), resized)

Output:

Skeletonization

Skeletonization 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.

For convenience, the skeletonize function of imutils can be used to construct the topological skeleton of the image.

The 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 , but can be any valid structuring element.

Example:

# skeletonize the image
gray = cv2.cvtColor(logo, cv2.COLOR_BGR2GRAY)
skeleton = imutils.skeletonize(gray, size=(3, 3))
cv2.imshow("Skeleton", skeleton)

Output:

Displaying with Matplotlib

In 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.

Example:

# INCORRECT: show the image without converting color spaces
plt.figure("Incorrect")
plt.imshow(cactus)

# CORRECT: convert color spaces before using plt.imshow
plt.figure("Correct")
plt.imshow(imutils.opencv2matplotlib(cactus))
plt.show()

Output:

URL to Image

This 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 on the PyImageSearch blog.

Example:

url = "http://pyimagesearch.com/static/pyimagesearch_logo_github.png"
logo = imutils.url_to_image(url)
cv2.imshow("URL to Image", logo)
cv2.waitKey(0)

Output:

Checking OpenCV Versions

OpenCV 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.

Example:

print("Your OpenCV version: {}".format(cv2.__version__))
print("Are you using OpenCV 2.X? {}".format(imutils.is_cv2()))
print("Are you using OpenCV 3.X? {}".format(imutils.is_cv3()))

Output:

Your OpenCV version: 3.0.0
Are you using OpenCV 2.X? False
Are you using OpenCV 3.X? True

Automatic Canny Edge Detection

The 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.

Example:

gray = cv2.cvtColor(logo, cv2.COLOR_BGR2GRAY)
edgeMap = imutils.auto_canny(gray)
cv2.imshow("Original", logo)
cv2.imshow("Automatic Edge Map", edgeMap)

Output:

4-point Perspective Transform

A 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.

Example

See the contents of demos/perspective_transform.py

Output:

Sorting Contours

The 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.

Example:

See the contents of demos/sorting_contours.py

Output:

(Recursively) Listing Paths to Images

The paths sub-module of imutils includes a function to recursively find images based on a root directory.

Example:

Assuming we are in the demos directory, let's list the contents of the ../demo_images:

from imutils import paths
for imagePath in paths.list_images("../demo_images"):
	print imagePath

Output:

../demo_images/bridge.jpg
../demo_images/cactus.jpg
../demo_images/notecard.png
../demo_images/pyimagesearch_logo.jpg
../demo_images/shapes.png
../demo_images/workspace.jpg

Comments

'NoneType' object has no attribute 'shape'
Hello; I‘m running the real_time_object_detection program，and the problem is ：D:\python3.5.2\Model\object-detection-deep-learning>python real_time_object_detection.py --prototxt=MobileNetSSD_deploy.prototxt.txt --model=MobileNetSSD_deploy.caffemodel [INFO] loading model... [INFO] starting video stream... Traceback (most recent call last): File "real_time_object_detection.py", line 44, in frame = imutils.resize(frame, width=400) File "C:\Anaconda3\lib\site-packages\imutils\convenience.py", line 69, in resize (h, w) = image.shape[:2] AttributeError: 'NoneType' object has no attribute 'shape'

the code is：

import the necessary packages

from imutils.video import VideoStream from imutils.video import FPS import numpy as np import argparse import imutils import time import cv2

construct the argument parse and parse the arguments

ap = argparse.ArgumentParser() ap.add_argument("-p", "--prototxt", required=True, help="path to Caffe'deploy'prototxt file") ap.add_argument("-m", "--model", required=True, help="path to Caffe pre-trained model") ap.add_argument("-c", "--confidence", type=float, default=0.2, help="minimum probability to filter weak detections") args = vars(ap.parse_args())

initialize the list of class labels MobileNet SSD was trained to

detect, then generate a set of bounding box colors for each class

CLASSES = ["background", "aeroplane", "bicycle", "bird", "boat", "bottle", "bus", "car", "cat", "chair", "cow", "diningtable", "dog", "horse", "motorbike", "person", "pottedplant", "sheep", "sofa", "train", "tvmonitor"] COLORS = np.random.uniform(0, 255, size=(len(CLASSES), 3))

load our serialized model from disk

print("[INFO] loading model...") net = cv2.dnn.readNetFromCaffe(args["prototxt"], args["model"])

initialize the video stream, allow the cammera sensor to warmup,

and initialize the FPS counter

print("[INFO] starting video stream...") vs = VideoStream(src=1).start() time.sleep(2.0) fps = FPS().start()

loop over the frames from the video stream

while True: # grab the frame from the threaded video stream and resize it # to have a maximum width of 400 pixels frame = vs.read() frame = imutils.resize(frame, width=400)

# grab the frame dimensions and convert it to a blob (h, w) = frame.shape[:2] blob = cv2.dnn.blobFromImage(frame, 0.007843, (300, 300), 127.5) # pass the blob through the network and obtain the detections and # predictions net.setInput(blob) detections = net.forward()

loop over the detections

for i in np.arange(0, detections.shape[2]): # extract the confidence (i.e., probability) associated with # the prediction confidence = detections[0, 0, i, 2] # filter out weak detections by ensuring the `confidence` is # greater than the minimum confidence if confidence > args["confidence"]: # extract the index of the class label from the # `detections`, then compute the (x, y)-coordinates of # the bounding box for the object idx = int(detections[0, 0, i, 1]) box = detections[0, 0, i, 3:7] * np.array([w, h, w, h]) (startX, startY, endX, endY) = box.astype("int") # draw the prediction on the frame label = "{}: {:.2f}%".format(CLASSES[idx], confidence * 100) cv2.rectangle(frame, (startX, startY), (endX, endY), COLORS[idx], 2) y = startY - 15 if startY - 15 > 15 else startY + 15 cv2.putText(frame, label, (startX, y), cv2.FONT_HERSHEY_SIMPLEX, 0.5, COLORS[idx], 2)

show the output frame

cv2.imshow("Frame", frame) key = cv2.waitKey(1) & 0xFF # if the `q` key was pressed, break from the loop if key == ord("q"): break # update the FPS counter fps.update()

stop the timer and display FPS information

fps.stop() print("[INFO] elapsed time: {:.2f}".format(fps.elapsed())) print("[INFO] approx. FPS: {:.2f}".format(fps.fps()))

do a bit of cleanup

cv2.destroyAllWindows() vs.stop()

may be the problem is it didn't active the camera when I was running “vs = VideoStream(src=1).start()”？ appreciated for helping me，Thank you.
opened by HeXu1 27
No module named 'imutils' after pip install
I just followed this guide here to install OpenCV: http://www.pyimagesearch.com/2016/12/19/install-opencv-3-on-macos-with-homebrew-the-easy-way/

And then followed this guide here: http://www.pyimagesearch.com/2016/02/08/opencv-shape-detection/

I've pip-installed imutils, but keep getting the error below.

sudo pip install imutils ... Collecting imutils Downloading imutils-0.4.2.tar.gz Installing collected packages: imutils Running setup.py install for imutils ... done Successfully installed imutils-0.4.2 hdmih0445m:shape-detection bstadin$

The install seems to be ok, trying to reinstall imutils gives:

Requirement already satisfied: imutils in /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages

Running a script importing imutils:

python3 detect_shapes.py --image /Users/bstadin/Downloads/image.png ... Traceback (most recent call last): File "detect_shapes.py", line 7, in <module> import imutils ModuleNotFoundError: No module named 'imutils'
opened by benstadin 26
ImportError: No module named imutils

Hello, I installed imutils in Ubuntu 16.04 using the next command:

sudo pip apt-get install imutils

I ran "pip list" and show me that imutils (0.4.3) is already installed, but when I tried to use it in a python script:

import imutils

show me the next error:

Traceback (most recent call last): File "/home/epic/Documentos/python test/OpenCV/curso/test2.py", line 3, in import imutils ImportError: No module named imutils

any idea what is wrong?

SALUDOS!!!!!!!!!!

opened by Loco123 22
Illegal instruction
Hello,

I have a python3 script on my computer that I can run with python3 motion_detection.py and that works, I tried to use it on my Raspberry and something fails with message Illegal instruction. The line that throws this error is: frame = imutils.resize(frame, width=500)

Here is the minimalist sample of code:

import imutils import cv2 frame = cv2.imread('test.jpg') frame = imutils.resize(frame, width=500)

I'm sure that frame is not None because I tried to save it and it worked. I'm a bit confused because there is no more explaination that Illegal instruction I checked the version of imutils that is the same on my computer that on the Raspberry (0.4.6)

Can someone help me please ?
opened by qlerebours 13
threaded frame rate slower than speficied
I have a code example, where the processing pipe's throughput is about 23 fps, while the framerate of PiVideoStream is specified to be 40. See the following code:

from __future__ import print_function from imutils.video.pivideostream import PiVideoStream from imutils.video import FPS import imutils import time import cv2 # function to return the difference of elementsums between consecutive frames. If it returns 0, # then the frames are identical with a high probability def diff(frame1,frame2): return(cv2.sumElems(frame1)[0]-cv2.sumElems(frame2)[0]) vs = PiVideoStream(resolution=(720,720),framerate=40).start() time.sleep(2.0) fps = FPS().start() diffs=[] frame2 = vs.read() while fps._numFrames < 50: frame1 = frame2 time.sleep(0.025) frame2 = vs.read() diffs.append(diff(frame1,frame2)) fps.update() fps.stop() print("[INFO] elasped time: {:.2f}".format(fps.elapsed())) print("[INFO] approx. FPS: {:.2f}".format(fps.fps())) print(diffs) cv2.destroyAllWindows() vs.stop()

The script is doing the following:

comparing two consecutive frames by subtracting the elementsums of each from each other. If the result is zero, then the frames must have been identical (since the scene is not static). The for loop is looping through several frames and storing consecutive differences to 'diffs'.

Remember, according to imutils.video.FPS my throughput is 23 frames per second. Therefore if the camera framerate is 40, and the PiVideoStream is actually working like it is supposed to do, then the elements of diffs should be all non-zero. But in fact up to 40% of the elements are zero. try it out The camera itself is surely able to handel 40fps. So there must be something with the implementation of threading.
opened by Amrosik 10
paths.py - replacing space with slash+space

Hi!

First of all, thanks for the library. Very useful! Second, I wanted to ask you why do you replace space with slash+space in paths.py? Is this a bug or something you've done on purpose?

imagePath = os.path.join(rootDir, filename).replace(" ", "\\ ")

PS: I'm using Windows and Python3.

opened by m3rik 8
FileVideoStream: do not call transform when stopping

Fixes:

read_frames_fast.py -v /home/swarthout/packages/sw/opencv/opencv_extra/testdata/highgui/video/big_buck_bunny.wmv [INFO] starting video file thread... Exception in thread Thread-1: Traceback (most recent call last): File "/usr/lib/python3.6/threading.py", line 916, in _bootstrap_inner self.run() File "/usr/lib/python3.6/threading.py", line 864, in run self._target(*self._args, **self._kwargs) File "/usr/local/lib/python3.6/dist-packages/imutils/video/filevideostream.py", line 67, in update frame = self.transform(frame) File "read_frames_fast.py", line 21, in filterFrame frame = imutils.resize(frame, width=450) File "/usr/local/lib/python3.6/dist-packages/imutils/convenience.py", line 69, in resize (h, w) = image.shape[:2] AttributeError: 'NoneType' object has no attribute 'shape'

[INFO] elasped time: 0.31 [INFO] approx. FPS: 402.98

Signed-off-by: Ed Swarthout [email protected]

opened by ghost 7
FileVideoStream Problem: FATAL: exception not rethrown Aborted (core dumped)

Code:

fvs = FileVideoStream("./1_2017-03-17_08-38-27.mp4") fvs.start() num = 0 while fvs.more(): frame = fvs.read() if frame is None: print("Break!") break print(num) num = num +1 print("finished!") fvs.stop()

First, It wouldn't print the number, that means fvs.more() doesn't work. And it would raise a ERROR at last. Notice, the path of video is on the way. How can I deal with my problem?

opened by knaffe 7

Add feature to convert python list of numpy images to grid images

Hi Adrian, I really like what you're doing with imutils and your blog, keep it up! I'd like to submit a feature make_grids_of_images to imutils as part of the convenience.py module if you approve:

Brief: Often I need to crawl image datasets which have large, convoluted folder structures. I find it useful to create some grid images to visualise the dataset as well and share with my colleagues.

Example usage - "The Perfect Desktop Background":

from imutils import convenience
import urllib
# get image from url, convert to numpy array
req = urllib.urlopen('https://avatars0.githubusercontent.com/u/7102778?v=3&s=460')
arr = np.asarray(bytearray(req.read()), dtype=np.uint8)
img = cv2.imdecode(arr, -1)
# duplicate image 'num_imgs' times
num_imgs = 35
img_list = []
for i in xrange(num_imgs):
    img_list.append(img)
# convert image list into a grid of 256x256 images tiled in a 7x5 grid
grids = convenience.make_grids_of_images(img_list, (256, 256), (7, 5))
# iterate through grids and display
for grid in grids:
    cv2.imshow('grid image', grid)
    cv2.waitKey(0)

Let me know what you think and feel free to refine/use as you wish. Cheers, Kyle

opened by kylehounslow 7

"resolution" and "framerate" parameters are ignored by VideoStream when using webcam source

According to https://github.com/jrosebr1/imutils/blob/master/imutils/video/videostream.py , the constructor arguments for resolution and fps are only used if the PI Camera is the source for the the videostream. Is this intentional?

opened by xoxota99 6
ImportError: No module named imutils

User-MacBook-Pro:~ user$ sudo pip install imutils

Collecting imutils Installing collected packages: imutils Successfully installed imutils-0.5.1 User-MacBook-Pro:~ user$ -H -bash: -H: command not found User-MacBook-Pro:~ user$ sudo -H pip install imutils Requirement already satisfied: imutils in /usr/local/lib/python2.7/site-packages (0.5.1)

Installed imutils for Python2.7 and when I checked whether it is importing imutils library successfully or not then it displayed the following error message:

User-MacBook-Pro:~ user$ python Python 2.7.14 (v2.7.14:84471935ed, Sep 16 2017, 12:01:12) [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin Type "help", "copyright", "credits" or "license" for more information.

import imutils Traceback (most recent call last): File "", line 1, in ImportError: No module named imutils

What is the problem here and how to fix it??

opened by jasch-shah 5
Can't parse center

This makes this error Can't parse 'Center'

The error comes from the aligner

File ~\AppData\Local\Programs\Python\Python310\lib\site-packages\imgphon\landmark.py:94, in get_norm_face(frame, detector, predictor, aligner) 89 rect = detector(gray,1)[0] 91 # align face 92 # TODO fork imutils, change this function to rotate and return the landmarks used for alignment; 93 # replace current marks_np ---> 94 faceAligned = aligner.align(frame, gray, rect) 96 return faceAligned

File ~\AppData\Local\Programs\Python\Python310\lib\site-packages\imutils\face_utils\facealigner.py:68, in FaceAligner.align(self, image, gray, rect) 64 eyesCenter = ((leftEyeCenter[0] + rightEyeCenter[0]) // 2, 65 (leftEyeCenter[1] + rightEyeCenter[1]) // 2) 67 # grab the rotation matrix for rotating and scaling the face ---> 68 M = cv2.getRotationMatrix2D(eyesCenter, angle, scale) 70 # update the translation component of the matrix 71 tX = self.desiredFaceWidth * 0.5

TypeError: Can't parse 'center'. Sequence item with index 0 has a wrong type

opened by BilalAlsharif 0
Remove dependency on scipy.

imutils depends on scipy just for calculating Euclidean distance in perspective.py. This dependency was adding significant size to our OpenCV layer for aws lambda functions that have a limit of 250 MB on package size when uncompressed.

scipy installed size ~ 185 MB zipped size ~ 58 MB

Current changes utilize numpy to achieve the same so that scipy dependency can be removed.

This resolves the issue: https://github.com/PyImageSearch/imutils/issues/175

opened by farqis 0
Automatically install dependencies when package is installed

All dependencies (NumPy, SciPy, Matplotlib, OpenCV) will be installed automatically when imutils is installed.

This is done using setuptools, since distutils doesn't support automatic installation of dependencies.

opened by sohang3112 0
Inverse of four_point_transform

Would it be possible to add an inverse of four_point_transform? It's an extremely useful function, but a lot of functionality is missing without an inverse.

Give it the image you wish to write to, preferably the same size as the image you got the points from in the first place, give it the transformed (and likely edited image), and then give it the points. Returns the first image with the transformed image untransformed and written to it.

opened by GameDungeon 0
Add support for skipping frames

Add support for skipping frames (in case videofile has malformed frames)

Add delegate call to get stream dimensions Replace long polling put queue with built-in blocking wait for put (with configurable timeout on instantiation)

opened by DarwinsBuddy 1

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.

Related tags

Overview

imutils

Installation

Finding function OpenCV functions by name

Example:

Output:

Translation

Example:

Output:

Rotation

Example:

Output:

Resizing

Example:

Output:

Skeletonization

Example:

Output:

Displaying with Matplotlib

Example:

Output:

URL to Image

Example:

Output:

Checking OpenCV Versions

Example:

Output:

Automatic Canny Edge Detection

Example:

Output:

4-point Perspective Transform

Example

Output:

Sorting Contours

Example:

Output:

(Recursively) Listing Paths to Images

Example:

Output:

Comments

import the necessary packages

construct the argument parse and parse the arguments

initialize the list of class labels MobileNet SSD was trained to

detect, then generate a set of bounding box colors for each class

load our serialized model from disk

initialize the video stream, allow the cammera sensor to warmup,

and initialize the FPS counter

loop over the frames from the video stream

loop over the detections

show the output frame

stop the timer and display FPS information

do a bit of cleanup

Owner

Adrian Rosebrock

Img-process-manual - Utilize Python Numpy and Matplotlib to realize OpenCV baisc image processing function

An image base contains 490 images for learning (400 cars and 90 boats), and another 21 images for testingAn image base contains 490 images for learning (400 cars and 90 boats), and another 21 images for testing

FID calculation with proper image resizing and quantization steps

Inkscape extensions for figure resizing and editing

Python-experiments - A Repository which contains python scripts to automate things and make your life easier with python

Snapchat-filters-app-opencv-python - Here we used opencv and other inbuilt python modules to create filter application like snapchat

Yolov5-opencv-cpp-python - Example of using ultralytics YOLO V5 with OpenCV 4.5.4, C++ and Python

This YoloV5 based model is fit to detect people and different types of land vehicles, and displaying their density on a fitted map, according to their coordinates and detected labels.

Matplotlib Image labeller for classifying images

Third party Pytorch implement of Image Processing Transformer (Pre-Trained Image Processing Transformer arXiv:2012.00364v2)

performing moving objects segmentation using image processing techniques with opencv and numpy

Deep Learning Datasets Maker is a QGIS plugin to make datasets creation easier for raster and vector data.

This project aim to create multi-label classification annotation tool to boost annotation speed and make it more easier.

This repository contains several image-to-image translation models, whcih were tested for RGB to NIR image generation. The models are Pix2Pix, Pix2PixHD, CycleGAN and PointWise.

A hobby project which includes a hand-gesture based virtual piano using a mobile phone camera and OpenCV library functions

A python-image-classification web application project, written in Python and served through the Flask Microframework. This Project implements the VGG16 covolutional neural network, through Keras and Tensorflow wrappers, to make predictions on uploaded images.

Script that receives an Image (original) and a set of images to be used as "pixels" in reconstruction of the Original image using the set of images as "pixels"

The Medical Detection Toolkit contains 2D + 3D implementations of prevalent object detectors such as Mask R-CNN, Retina Net, Retina U-Net, as well as a training and inference framework focused on dealing with medical images.