Python OpenCV Utilities

Python OpenCV Utilities provides useful extensions for OpenCV and can be used as a drop-in replacement for cv2.

import cv2u as cv  # instead of: import cv2 as cv

Installation

pip install python-opencv-utils
pip install "python-opencv-utils[cluster]"  # also installs scikit-learn (meanShiftColors, DBSCAN, clusterPoints)

Dependencies (installed automatically): opencv-python>=5, numpy>=2, pillow. The optional cluster extra adds scikit-learn for meanShiftColors, DBSCAN and clusterPoints. dominantColors, colorQuantize and kmeansColors work without it (they use cv.kmeans).

Usage

The official OpenCV Python tutorials import the module as import cv2 as cv. Use the same pattern with cv2u: every OpenCV function and constant keeps working, and the extensions below are available alongside them.

import cv2u as cv

src = cv.imread("image.jpg")  # plain OpenCV
dst = cv.rotateEx(src, 45)  # cv2u extension

If a name exists in both, the cv2u version wins. You can always reach the original module with import cv2. cv is only a name, so import cv2u as cv2 also works if you prefer it.

Type checkers and IDEs see OpenCV's own signatures through cv2u, so autocompletion and type checking for cv.imread and friends keep working. Names added in OpenCV releases newer than 5.0 are typed as Any.

Everyday helpers

import cv2u as cv

src = cv.imreadEx("C:/사진/고양이.jpg")  # cv.imread fails on non-ASCII paths on Windows
small = cv.resizeEx(src, width=640)  # keeps the aspect ratio
boxed, scale, (left, top) = cv.letterbox(src, (640, 640))  # fit + pad, e.g. for a model input
logo = cv.imread("logo.png", cv.IMREAD_UNCHANGED)  # BGRA with transparency
stamped = cv.overlayImage(small, logo, org=(10, 10), opacity=0.8)
cv.imwriteEx("C:/사진/비교.png", cv.hconcatEx([small, stamped], gap=8))

Video and notebooks

import cv2u as cv

print(cv.videoInfo("input.mp4"))  # VideoInfo(width=1920, height=1080, fps=30.0, frameCount=900)
edges = (cv.autoCanny(frame) for frame in cv.readFrames("input.mp4", step=2))  # every 2nd frame
cv.writeVideo("edges.mp4", edges, fps=15)  # codec, size and color mode are detected

corners = [[120, 80], [980, 140], [940, 760], [90, 700]]  # e.g. from cv.approxPolyDP, in any order
page = cv.fourPointTransform(cv.imread("photo.jpg"), corners)
cv.imshowInline(page)  # in Jupyter, with the correct colors

Detection and web results

import cv2u as cv

img = cv.imread("street.jpg")
detections = [((40, 60, 120, 200), "person", 0.94), ((200, 90, 160, 110), "자동차", 0.88)]
crops = []
for box, name, score in detections:
    crops.append(cv.cropEx(img, box, margin=10, fill=0))  # safe even at the image border
    cv.drawLabel(img, box, f"{name} {score:.2f}", (0, 200, 255), fontPath="C:/Windows/Fonts/malgun.ttf")

hsv = cv.cvtColor(img, cv.COLOR_BGR2HSV)
red = cv.inRangeEx(hsv, (170, 80, 80), (10, 255, 255))  # red wraps around hue 0
cv.imwrite("result.png", cv.montage([img, cv.overlayMask(img, red, (255, 0, 255)), *crops], gap=8))

payload = {"image": cv.imencodeBase64(img, ".jpg", dataUri=True)}  # for a JSON API or an HTML <img>

rotateEx

Rotates an image without cropping its corners. The canvas grows to fit the result.

import cv2u as cv

src = cv.imread("image.jpg")
dst = cv.rotateEx(src, 45)

cv.imshow("src", src)
cv.imshow("dst", dst)
cv.waitKey()

src	dst

Masks, contours and templates

import cv2u as cv

scan = cv.cropToContent(cv.imread("scan.png"), tolerance=10)  # drop the white margin
mask = cv.inRange(cv.toGray(scan), 0, 100)  # dark ink; toGray works whatever the input is
mask = cv.fillHoles(cv.removeSmallObjects(mask, minArea=30))
for contour in cv.findContoursEx(mask, minArea=500)[:3]:  # the 3 largest shapes
    cv.drawLabel(scan, cv.boundingRect(contour), f"{cv.contourArea(contour):.0f} px", (0, 160, 255))

for x, y, w, h, score in cv.findTemplate(scan, cv.imread("logo.png"), threshold=0.9):
    print(f"logo at ({x}, {y}), score {score:.2f}")
cv.imwriteEx("out/annotated.png", scan, makeDirs=True)  # cv.imwrite would return False: no "out" folder

Color clustering

Every color clustering returns (maps, centers): a label image and one color per label, so centers[maps] paints the result. They differ in how the number of colors is chosen:

Timings: the scene above at 1200x800 and 4200x2800, best of 3 runs, on one Windows PC with Python 3.14; use them to compare the methods, not as absolute numbers.

peakColors is cv2u's own method: it counts the pixels in a 3-D Lab color histogram, smooths it, and follows every histogram cell uphill to its peak; each peak becomes one color. Identical colors, which are very common in 8-bit images, simply add up, so it neither needs a sample nor splits flat colors apart. In the comparison it found the 5 regions of the scene, where kmeansColors (with a fixed k=6) cut the sky gradient with a noisy band, and meanShiftColors added two clusters of 421 and 79 pixels. bins and sigma make it finer or coarser, and minRegion absorbs small speckles into the surrounding region.

On a real photo of a sneaker, peakColors separates background, the dark and bright greens and the white parts into 4 clean regions. meanShiftColors finds 6 colors but leaves the surface speckled, and DBSCAN with eps=1.7 splits the image into 496 tiny clusters, which mostly reproduces the input. Note that the dark-red star (15 pixels, 0.04% of the image, almost black) merges into the background with every color clustering except that very fine DBSCAN; details this small are below what a palette can keep.

import cv2u as cv

img = cv.imread("photo.jpg")
maps, centers = cv.peakColors(img)  # number of colors found automatically, no extra needed
print(len(centers), "colors")
segmented = centers[maps]

for (b, g, r), share in cv.dominantColors(img, k=5):  # a palette
    print(f"#{r:02x}{g:02x}{b:02x} {share:.0%}")
poster = cv.colorQuantize(img, 8)

Named flags

import cv2u as cv

src = cv.imread("image.jpg")
mirrored = cv.flip(src, cv.FLIP_MODE_Y)  # instead of cv.flip(src, 1)
edges = cv.Sobel(src, cv.DDEPTH_SAME, 1, 0)  # instead of ddepth=-1
gray = cv.cvtColor(src, cv.COLOR_BGR2GRAY)
contours, _ = cv.findContours(cv.Canny(gray, 100, 200), cv.RETR_EXTERNAL, cv.CHAIN_APPROX_SIMPLE)
cv.drawContours(src, contours, cv.ALL_CONTOURS, (0, 255, 0), cv.FILLED)  # instead of contourIdx=-1

cv.imshow("mirrored", mirrored)
while cv.waitKey(cv.WAIT_FOREVER) != cv.KEY_ESC:  # instead of waitKey(0) != 27
    pass

Design principles

cv2u is what you wish OpenCV had, in the place you would look for it:

1. Fill the gaps in OpenCV: only add what OpenCV lacks or makes you write boilerplate for.
2. Look like OpenCV: same module names, camelCase, Ex for extended versions, src first, BGR, OpenCV parameter names.
3. Never shadow OpenCV: no extension has the same name as anything in cv2.
4. Stay light: heavier dependencies are optional extras.
5. Typed and validated: type hints everywhere, clear ValueErrors for bad input.
6. Change carefully: after a release, renames get deprecated aliases and new behavior goes behind new parameters.

Details: https://076923.github.io/cv2-utils/principles/

API

Full reference with parameters and exceptions: https://076923.github.io/cv2-utils/api/

core

imgcodecs

imgproc

videoio

highgui

flag

Named constants for magic numbers that OpenCV takes without a constant of its own.

Development

See CONTRIBUTING.md. Release notes are in CHANGELOG.md. Please follow the Code of Conduct, and report security issues as described in SECURITY.md. To cite this project, use CITATION.cff (GitHub shows a "Cite this repository" button).

Authors

Daehee Yun (s076923@gmail.com)

License

Apache License 2.0