imutils: Image Processing Utility Functions

0.5.4 · maintenance · verified Mon Apr 13

imutils is a Python package providing a series of convenience functions to simplify basic image processing operations such as translation, rotation, resizing, skeletonization, displaying Matplotlib images, sorting contours, and detecting edges. It acts as a companion library to OpenCV, streamlining common tasks and reducing boilerplate code. The current version is 0.5.4, released on January 15, 2021. The library has a slow release cadence, with no new versions in over three years, suggesting it is in maintenance mode rather than active development.

Warnings

breaking As of late 2024, `imutils` has faced installation issues (e.g., `error: metadata-generation-failed`) for some users due to its reliance on `distutils` and `setup.py`, which are deprecated in newer Python/pip environments. The project also appears to be unmaintained, with no recent updates or fixes to these issues.
Fix: Consider alternatives for specific functionalities or manually install dependencies if encountering build errors. Users have reported issues on GitHub related to `setuptools` not being available in the build environment.
gotcha Imutils is a wrapper around OpenCV; therefore, `opencv-python` (or `opencv-contrib-python`) is a crucial, unlisted peer dependency. Trying to use `imutils` without `opencv-python` installed will result in `ImportError: No module named 'cv2'`.
Fix: Ensure `opencv-python` is installed: `pip install opencv-python`.
gotcha Similar to OpenCV, `imutils` operations often rely on NumPy arrays. Forgetting to install `numpy` can lead to `ModuleNotFoundError: No module named 'numpy'` or other runtime errors.
Fix: Ensure `numpy` is installed: `pip install numpy`.
gotcha When displaying images using Matplotlib, remember that OpenCV (and by extension, `imutils` results) stores images in BGR format, while Matplotlib expects RGB. Displaying a BGR image directly with Matplotlib will result in incorrect color representation (e.g., blue appears red and vice-versa).
Fix: Convert the image from BGR to RGB before displaying with Matplotlib: `image_rgb = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB)`.

Install

pip install imutils Install imutils via pip

Imports

imutils
```
import imutils
```
resize
```
from imutils import resize
```
rotate
```
from imutils import rotate
```
translate
```
from imutils import translate
```
VideoStream
```
from imutils.video import VideoStream
```
FPS
```
from imutils.video import FPS
```
grab_contours
```
from imutils.contours import grab_contours
```
Some older examples might show direct access, but it's typically found in `imutils.contours`.

Quickstart

This quickstart demonstrates how to use `imutils.resize` to scale an image while preserving its aspect ratio. It first creates a dummy image (you'd typically load one with `cv2.imread`) and then resizes it to a specified width. Both the original and resized images are displayed using OpenCV's `imshow` function.

import cv2
import imutils
import numpy as np

# Simulate reading an image (replace with cv2.imread('path/to/image.jpg'))
# For demonstration, create a dummy black image (BGR format)
image = np.zeros((300, 500, 3), dtype="uint8")
cv2.putText(image, "Original Image", (100, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)

# Use imutils.resize to resize the image while maintaining aspect ratio
resized_image = imutils.resize(image, width=150)

# Display original and resized images
cv2.imshow("Original", image)
cv2.imshow("Resized (width=150)", resized_image)

cv2.waitKey(0)
cv2.destroyAllWindows()

view raw JSON →