С чего начать
Чтение, показ и сохранение изображений
OpenCV читает изображения в порядке BGR (а не RGB) — частая ловушка при взаимодействии с matplotlib или PIL. cv2.waitKey(0) блокируется до нажатия клавиши; в сегда вызывайте destroyAllWindows(), чтобы закрыть окна. Качество JPEG — от 0 до 100.
import cv2
import numpy as np
# read an image (BGR format by default)
img = cv2.imread("photo.jpg")
print(img.shape) # (height, width, channels)
# read as grayscale
gray = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# read with alpha channel
rgba = cv2.imread("logo.png", cv2.IMREAD_UNCHANGED)
# display
cv2.imshow("window", img)
cv2.waitKey(0)
cv2.destroyAllWindows()
# save
cv2.imwrite("output.jpg", img, [cv2.IMWRITE_JPEG_QUALITY, 90])Установка и импорт
opencv-python поставляется только с основными модулями; opencv-contrib-python добавляет дополнительные (часто обременённые патентами) модули вроде SIFT/SURF и ArUco. На серверах и в Docker используйте headless-вариант, чтобы не тянуть зависимости X11. Несмотря на имя cv2, OpenCV 4.x по-прежнему импортируется как cv2.
# Install OpenCV (Python bindings)
pip install opencv-python # main modules only
pip install opencv-contrib-python # includes extra modules (SIFT, SURF, aruco...)
pip install opencv-python-headless # no GUI (servers / Docker)
# The universal alias is cv2
import cv2
print(cv2.__version__) # e.g. 4.9.0
# NumPy is required — images are ndarray
import numpy as npИзображение как массив NumPy
Изображения OpenCV — это массивы NumPy, поэтому всё, что вы знаете о NumPy, применимо. Соглашение координат — img[y, x] (строка, столбец), противоположное координатам изображения (x, y), — частый источник багов. Цветные изображения имеют форму (H, W, 3) в BGR; оттенки серого — (H, W).
import cv2
import numpy as np
img = cv2.imread("photo.jpg") # BGR uint8, shape (H, W, 3)
print(type(img)) # <class 'numpy.ndarray'>
print(img.shape, img.dtype) # (480, 640, 3) uint8
# A grayscale image is 2-D: (H, W)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print(gray.shape) # (480, 640)
# Coordinate convention: img[y, x] (row, col)
px = img[100, 200] # BGR pixel at (x=200, y=100)
blue, green, red = img[100, 200]
# Vectorized access to a region (ROI)
roi = img[50:150, 100:300] # rows 50-149, cols 100-299До ступ к пикселям и ROI
Доступ к каждому пикселю через img[y, x] медленный и не рекомендуется в циклах — всегда предпочитайте срезы NumPy. Делайте .copy() при присваивании ROI, чтобы последующие изменения источника не просачивались. Изменение img[:, :, channel] — самый быстрый способ работы с отдельным цветовым каналом.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# access a single pixel (slow)
b, g, r = img[100, 200]
# access a single channel faster
blue = img[100, 200, 0]
img[100, 200] = [255, 255, 255] # set to white
# numpy slicing is much faster than item-by-item
roi = img[100:200, 200:400].copy()
# copy ROI to another location
img[0:100, 0:200] = roi
# modify a whole channel
img[:, :, 2] = 0 # zero out the red channelТипы данных и преобразование
Большинство функций OpenCV ожидают uint8 (0–255), но алгоритмы вроде SIFT, оптического потока и обнаружения краёв часто требуют float32. Никогда не приводите напрямую через .astype() после вычитания: переполнение uint8 превращает -1 в 255. Используйте cv2.absdiff или сначала переводите в float. Всегда приводите обратно к uint8 перед cv2.imwrite / imshow.
import cv2
import numpy as np
img = cv2.imread("photo.jpg") # uint8, 0-255
print(img.dtype, img.min(), img.max()) # uint8 0 255
# convert to float32 (0.0-1.0 for many algorithms)
f = img.astype(np.float32) / 255.0
# convert back to uint8 for display/save
u = (f * 255).astype(np.uint8)
# clamp then cast (avoid overflow when subtracting)
diff = cv2.absdiff(img, img) # safe subtraction
print(diff.dtype) # uint8
# CV_32F / CV_64F / CV_8U constants (used in some functions)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print(gray.dtype) # uint8Захват видео
Открытие вебкамеры
VideoCapture(0) открывает вебкамеру по умолчанию; используйте 1, 2... для дополнительных камер. Всегда вызывайте cap.release(), чтобы освободить устройство: если забыть, камера может остаться занятой для других приложений. waitKey(1) ждёт ~1 мс; трюк с & 0xFF обеспечивает совместимость на 64-битных системах, где waitKey возвращает больше 8 бит.
import cv2
cap = cv2.VideoCapture(0) # 0 = default camera
print(cap.isOpened()) # True if camera opened
while True:
ret, frame = cap.read() # ret is False at end of stream
if not ret:
break
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
cv2.imshow("frame", gray)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Чтение видеофайла
CAP_PROP_FRAME_COUNT часто приблизителен и ненадёжен для некоторых кодеков — не полагайтесь на него при точной перемотке. waitKey(int(1000/fps)) воспроизводит примерно с правильной скоростью; для точного тайминга используйте реальные часы. Некоторые сжатые видео не откроются без нужного бэкенда (FFmpeg).
import cv2
cap = cv2.VideoCapture("movie.mp4")
# video properties
fps = cap.get(cv2.CAP_PROP_FPS)
width = cap.get(cv2.CAP_PROP_FRAME_WIDTH)
height = cap.get(cv2.CAP_PROP_FRAME_HEIGHT)
count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
print(f"{width}x{height} @ {fps} fps, {count} frames")
while cap.isOpened():
ret, frame = cap.read()
if not ret:
break
cv2.imshow("video", frame)
if cv2.waitKey(int(1000 / fps)) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Сохранение и запись видео
Код FourCC зависит от п латформы и кодека: 'mp4v' широко переносим, 'XVID' даёт .avi, 'avc1' — H.264 (может быть недоступен без проприетарных кодеков). Размер кадров, переданный в VideoWriter, ДОЛЖЕН совпадать с записываемыми кадрами, иначе файл будет повреждён. Всегда вызывайте out.release(), чтобы сбросить буфер и закрыть файл.
import cv2
cap = cv2.VideoCapture(0)
fourcc = cv2.VideoWriter_fourcc(*'mp4v') # or 'XVID', 'avc1'
fps = 20.0
size = (640, 480)
out = cv2.VideoWriter("out.mp4", fourcc, fps, size)
while cap.isOpened():
ret, frame = cap.read()
if not ret:
break
frame = cv2.resize(frame, size)
out.write(frame)
cv2.imshow("rec", frame)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()
out.release()
cv2.destroyAllWindows()Настройки камеры
Свойства камеры зависят от оборудования и драйвера: многие вебкамеры молча игнорируют неподдерживаемые настройки или привязываются к ближайшему допустимому значению, поэтому всегда читайте фактическое значение обратно. CAP_PROP_EXPOSURE использует log2 от секунд (-4 = 1/16 с). На большинстве камер автоэкспозицию нужно отключить (установить 1), прежде чем ручная экспозиция начнёт действовать.
import cv2
cap = cv2.VideoCapture(0)
# set resolution
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280)
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720)
# set exposure / focus / brightness
cap.set(cv2.CAP_PROP_EXPOSURE, -4) # log2 exposure time
cap.set(cv2.CAP_PROP_BRIGHTNESS, 128)
cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 1) # 1=manual, 3=auto
# disable autofocus and set manual focus
cap.set(cv2.CAP_PROP_AUTOFOCUS, 0)
cap.set(cv2.CAP_PROP_FOCUS, 50)
print(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) # actual width may differЧастота кадров и тайминг
cap.get(CAP_PROP_FPS) возвращает настроенный FPS, а не фактическую частоту захвата — измеряйте реальными часами. Скользящее среднее по 30 кадрам сглаживает дрожание. Главные убийцы FPS — cv2.imshow (поток GUI) и cv2.imwrite на каждый кадр; для бенчмарка отключайте отображение. Для детерминированного тайминга накапливайте кадры в потоке и обрабатывайте из очереди.
import cv2
import time
cap = cv2.VideoCapture(0)
prev = time.time()
fps_hist = []
while True:
ret, frame = cap.read()
if not ret:
break
now = time.time()
dt = now - prev
prev = now
if dt > 0:
fps_hist.append(1.0 / dt)
fps = sum(fps_hist[-30:]) / min(len(fps_hist), 30)
cv2.putText(frame, f"FPS: {fps:.1f}", (10, 30),
cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
cv2.imshow("fps", frame)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Рисование
Линия и прямоугольник
Все функции рисования изменяют изображение на месте — передавайте копию, если нужен оригинал. Координаты — (x, y), противоположно индексации NumPy [y, x]. Цвета — кортежи BGR. Используйте thickness=-1 для залитых фигур и cv2.LINE_AA для сглаженных (антиалиасинговых) линий на диагональных краях.
import cv2
import numpy as np
img = np.zeros((400, 400, 3), dtype=np.uint8)
# line(img, pt1, pt2, color, thickness)
cv2.line(img, (10, 10), (390, 10), (0, 255, 0), 2)
# rectangle(img, pt1, pt2, color, thickness)
cv2.rectangle(img, (50, 50), (200, 150), (255, 0, 0), 3)
# filled rectangle (thickness = -1)
cv2.rectangle(img, (220, 50), (370, 150), (0, 0, 255), -1)
# anti-aliased line (cv2.LINE_AA)
cv2.line(img, (10, 380), (390, 200), (255, 255, 0), 1, cv2.LINE_AA)
cv2.imshow("img", img)
cv2.waitKey(0)Круг и эллипс
Параметр axes у ellipse — (полуширина, полувысота), полная ширина равна 2 * axes[0]. angle поворачивает весь эллипс; startAngle/endAngle рисуют частичные дуги (0° — вправо, против часовой стрелки). Рисование частичных дуг — стандартный способ отображать сектора круговых диаграмм или индикаторы направления движения.
import cv2
import numpy as np
img = np.zeros((400, 400, 3), dtype=np.uint8)
# circle(img, center, radius, color, thickness)
cv2.circle(img, (100, 100), 50, (0, 255, 255), 3)
cv2.circle(img, (300, 100), 50, (255, 0, 255), -1) # filled
# ellipse(img, center, axes, angle, startAngle, endAngle, color, thickness)
cv2.ellipse(img, (200, 250), (100, 50), 30, 0, 360, (0, 255, 0), 2)
# partial arc (0 to 180 degrees)
cv2.ellipse(img, (200, 250), (100, 50), 30, 0, 180, (0, 0, 255), 3)
cv2.imshow("img", img)
cv2.waitKey(0)Полигон и ломаные
polylines принимает список массивов точек, поэтому можно нарисовать несколько полигонов за один вызов. Массив точек должен быть int32 и иметь форму (-1, 1, 2). Для залитых фигур используйте fillPoly; для полупрозрачной заливки рисуйте на оверлее и смешивайте через addWeighted. Флаг isClosed соединяет последнюю точку с первой.
import cv2
import numpy as np
img = np.zeros((400, 400, 3), dtype=np.uint8)
# polygon points: shape (N, 1, 2), int32
pts = np.array([[50, 50], [200, 30], [350, 200],
[300, 350], [80, 300]], dtype=np.int32)
pts = pts.reshape((-1, 1, 2))
# outline only (not closed)
cv2.polylines(img, [pts], False, (0, 255, 0), 2)
# closed polygon outline
cv2.polylines(img, [pts], True, (255, 0, 0), 3)
# filled polygon
cv2.fillPoly(img, [pts], (0, 0, 255))
cv2.imshow("img", img)
cv2.waitKey(0)Текст
Встроенные шрифты OpenCV — векторные шрифты Hershey: они не поддерживают CJK/ китайские символы. Для нелатинского текста рендерите через ImageFont из PIL (Pillow) и конвертируйте обратно или используйте cv2.freetype из opencv-contrib. getTextSize возвращает ((ширина, высота), базовую линию) — полезно для центрирования текста или фона под ним.
import cv2
import numpy as np
img = np.zeros((300, 600, 3), dtype=np.uint8)
# putText(img, text, org, fontFace, fontScale, color, thickness)
cv2.putText(img, "Hello OpenCV", (10, 50),
cv2.FONT_HERSHEY_SIMPLEX, 1.2, (255, 255, 255), 2)
# fonts
fonts = [cv2.FONT_HERSHEY_SIMPLEX, cv2.FONT_HERSHEY_PLAIN,
cv2.FONT_HERSHEY_DUPLEX, cv2.FONT_HERSHEY_COMPLEX,
cv2.FONT_HERSHEY_TRIPLEX, cv2.FONT_ITALIC]
for i, f in enumerate(fonts):
cv2.putText(img, f"font {i}", (10, 100 + i*30), f, 0.8, (0, 255, 0), 1)
# measure text size before drawing
(text_w, text_h), baseline = cv2.getTextSize(
"Measured", cv2.FONT_HERSHEY_SIMPLEX, 1.0, 2)
cv2.rectangle(img, (10, 260), (10 + text_w, 260 + text_h + baseline),
(0, 0, 255), 1)Стрелка и маркер
tipLength у arrowedLine — доля длины линии, поэтому у длинных стрелок наконечники пропорционально больше; задавайте его явно, если нужен одинаковый размер наконечников. drawMarker удобен для выделения ключевых точек (например, найденных признаков или углов); MARKER_TILTED_CROSS даёт маркер в форме X.
import cv2
import numpy as np
img = np.zeros((400, 400, 3), dtype=np.uint8)
# arrowedLine(img, pt1, pt2, color, thickness, tipLength)
cv2.arrowedLine(img, (50, 50), (350, 50), (0, 255, 0), 2, tipLength=0.05)
cv2.arrowedLine(img, (200, 200), (200, 380), (0, 0, 255), 3, tipLength=0.1)
# drawMarker (cross, tilted cross, circle, square, diamond)
cv2.drawMarker(img, (100, 300), (255, 0, 255),
markerType=cv2.MARKER_CROSS, markerSize=30, thickness=2)
cv2.drawMarker(img, (300, 300), (255, 255, 0),
markerType=cv2.MARKER_DIAMOND, markerSize=30, thickness=2)
cv2.imshow("img", img)
cv2.waitKey(0)Оверлей и аннотации
Техника оверлея (рисовать на копии, затем addWeighted) — стандартный способ полупрозрачной заливки: у OpenCV нет нативной альфы для фигур. Всегда рисуйте сплошной текст ПОСЛЕ смешивания, чтобы он оставался чётким; текст на оверлее до смешивания становится размытым. Этот паттерн повсюду в визуализации детекции и сегментации.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
overlay = img.copy()
# draw a translucent rectangle on the overlay
cv2.rectangle(overlay, (50, 50), (250, 150), (0, 0, 255), -1)
cv2.putText(overlay, "REGION", (60, 110),
cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
# blend overlay onto the original (alpha=0.4)
out = cv2.addWeighted(overlay, 0.4, img, 0.6, 0)
cv2.imshow("out", out)
cv2.waitKey(0)Арифметика изображений
Сложение и вычитание
cv2.add в OpenCV насыщается на 255 (250 + 10 = 255), а + в NumPy заворачивается (250 + 10 = 8 из-за переполнения uint8). Для изображений всегда используйте cv2.add / cv2.subtract: заворачивание создаёт видимые чёрные и белые артефакты. absdiff — рабочая лошадка вычитания фона и обнаружения движения.
import cv2
import numpy as np
a = cv2.imread("a.jpg")
b = cv2.imread("b.jpg")
b = cv2.resize(b, (a.shape[1], a.shape[0])) # match sizes
# OpenCV addition: saturated (caps at 255)
add_cv = cv2.add(a, b)
# NumPy addition: wraps around (250 + 10 = 264 -> 8)
add_np = a + b
# subtract (saturated, never goes below 0)
sub = cv2.subtract(a, b)
# absolute difference (handy for motion detection)
diff = cv2.absdiff(a, b)Смешивание и addWeighted
addWeighted требует, чтобы оба изображения имели одинаковый размер и dtype, — сначала измените размер. Член gamma добавляет константу к каждому пикселю, что полезно для управления яркостью. Классическое затухание и кросс-фейд между двумя изображениями — это просто addWeighted с alpha от 0 до 1.
import cv2
import numpy as np
a = cv2.imread("a.jpg")
b = cv2.imread("b.jpg")
b = cv2.resize(b, (a.shape[1], a.shape[0]))
# dst = alpha * a + beta * b + gamma
blend = cv2.addWeighted(a, 0.7, b, 0.3, 0)
# brighten by adding a constant (gamma)
bright = cv2.addWeighted(a, 1.0, a, 0.0, 50)
# fade between two images over N steps
for i in range(11):
alpha = i / 10.0
frame = cv2.addWeighted(a, alpha, b, 1 - alpha, 0)
cv2.imshow("fade", frame)
cv2.waitKey(200)Побитовые операции
Побитовые операции — стандартный способ применить маску: cv2.bitwise_or(src, dst, mask=mask) копирует src в dst только там, где маска ненулевая. Маска должна быть одноканальным 8-битным изображением, где ненулевое означает «оставить». Это основа извлечения ROI и замены фона.
import cv2
import numpy as np
a = np.zeros((200, 200), dtype=np.uint8)
cv2.rectangle(a, (20, 20), (120, 120), 255, -1)
b = np.zeros((200, 200), dtype=np.uint8)
cv2.circle(b, (100, 100), 60, 255, -1)
# bitwise AND / OR / XOR / NOT
and_ = cv2.bitwise_and(a, b)
or_ = cv2.bitwise_or(a, b)
xor = cv2.bitwise_xor(a, b)
not_ = cv2.bitwise_not(a)
# use a mask to copy only part of an image
mask = np.zeros((200, 200), dtype=np.uint8)
cv2.circle(mask, (100, 100), 50, 255, -1)
src = np.full((200, 200, 3), (0, 255, 0), dtype=np.uint8)
dst = cv2.imread("photo.jpg")
dst = cv2.resize(dst, (200, 200))
result = cv2.bitwise_or(src, dst, mask=mask)Разность изображений и движение
Разность кадров — простейший детектор движения: пороговое преобразование абсолютной разницы соседних кадров. Он ломается при движении камеры и игнорирует медленное движение — для реальных систем используйте вычитание фона (cv2.createBackgroundSubtractorMOG2) или оптический поток. Морфологическое открытие убирает шум, дилатация сливает близкие пятна.
import cv2
import numpy as np
prev = cv2.imread("frame1.jpg", cv2.IMREAD_GRAYSCALE)
curr = cv2.imread("frame2.jpg", cv2.IMREAD_GRAYSCALE)
# absolute difference
diff = cv2.absdiff(prev, curr)
# threshold to get a binary motion mask
_, mask = cv2.threshold(diff, 25, 255, cv2.THRESH_BINARY)
# clean up with morphology
kernel = np.ones((5, 5), np.uint8)
mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
mask = cv2.dilate(mask, kernel, iterations=2)
# find moving contours
contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
if cv2.contourArea(c) > 500:
x, y, w, h = cv2.boundingRect(c)
cv2.rectangle(curr, (x, y), (x+w, y+h), (0, 255, 0), 2)ROI и маскирование
bitwise_and с маской — идиоматический способ извлечь неправильные области. Булева индексация NumPy (img[mask]) гибче, но возвращает плоский массив пикселей, а не изображение нужной формы. Всегда делайте .copy() для ROI, которые планируете переиспользовать: срез возвращает представление, разделяющее оригинал.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# build a mask: white circle on black background
mask = np.zeros((h, w), dtype=np.uint8)
cv2.circle(mask, (w // 2, h // 2), 150, 255, -1)
# keep only the masked region, zero elsewhere
masked = cv2.bitwise_and(img, img, mask=mask)
# extract ROI by bounding box
roi = img[100:300, 200:500].copy()
# put ROI back (or to a different location)
img[0:200, 0:300] = roi
# boolean mask (NumPy) — also works, but converts to 0/255
bool_mask = np.zeros((h, w), dtype=bool)
bool_mask[100:300, 200:500] = True
img_masked = img.copy()
img_masked[~bool_mask] = 0Насыщение против заворачивания
Ловушка переполнения uint8: NumPy заворачивает (300 -> 44), OpenCV насыщает (300 -> 255). Для любой арифметики, которая может выйти за 0–255, используйте cv2.add/subtract или сначала переводите в int16/float32 и затем ограничивайте. Смешивание операций cv2 и NumPy в одном конвейере — главная причина загадочных тёмных и светлых артефактов на пикселях.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# WRONG: NumPy arithmetic wraps around (200 + 100 -> 44)
bad = img + 100
# RIGHT: cv2.add saturates at 255 (200 + 100 -> 255)
good = cv2.add(img, np.full_like(img, 100))
# subtracting a bright image: cv2 clamps to 0
dark = cv2.subtract(img, np.full_like(img, 100))
# manual saturation (equivalent to cv2.add)
manual = np.clip(img.astype(np.int16) + 100, 0, 255).astype(np.uint8)
# mixing cv2 and numpy is a common bug source:
# half = img // 2 # NumPy: fine (no overflow)
# half_then_add = half + half # might equal original (ok)
# but bright = img + img # wraps! 150+150=300 -> 44Геометрические преобразования
Масштабирование
INTER_AREA лучше для уменьшения (избегает алиасинга), INTER_CUBIC или INTER_LINEAR — для увеличения. INTER_NEAREST самый быстрый, но блочный — используется для изображений меток и масок, где нельзя вводить новые значения пикселей. Кортеж dsize — (ширина, высота), противоположно img.shape, где (высота, ширина).
import cv2
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# resize to a fixed size
small = cv2.resize(img, (320, 240))
# resize by a scale factor (fx, fy)
big = cv2.resize(img, None, fx=2.0, fy=2.0)
# resize keeping aspect ratio
scale = 0.5
new = cv2.resize(img, (int(w * scale), int(h * scale)))
# interpolation methods
down = cv2.resize(img, (w // 2, h // 2),
interpolation=cv2.INTER_AREA) # shrinking
up = cv2.resize(img, (w * 2, h * 2),
interpolation=cv2.INTER_CUBIC) # enlargingПоворот
cv2.rotate гораздо быстрее warpAffine для кратных 90°. Угол в getRotationMatrix2D задаётся в градусах, положительный — против часовой стрелки. Чтобы повернуть без обрезки, пересчитайте ограничивающий прямоуголь ник (new_w, new_h) и сдвиньте матрицу поворота, иначе углы большого повёрнутого изображения срежутся.
import cv2
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# rotate 90/180/270 (fast, no interpolation)
rot90 = cv2.rotate(img, cv2.ROTATE_90_CLOCKWISE)
rot180 = cv2.rotate(img, cv2.ROTATE_180)
rot270 = cv2.rotate(img, cv2.ROTATE_90_COUNTERCLOCKWISE)
# arbitrary-angle rotation
center = (w // 2, h // 2)
angle = 45
scale = 1.0
M = cv2.getRotationMatrix2D(center, angle, scale)
rot = cv2.warpAffine(img, M, (w, h))
# rotate and expand the canvas to fit the whole image
cos = abs(M[0, 0]); sin = abs(M[0, 1])
new_w = int(h * sin + w * cos)
new_h = int(h * cos + w * sin)
M[0, 2] += (new_w - w) / 2
M[1, 2] += (new_h - h) / 2
rot_fit = cv2.warpAffine(img, M, (new_w, new_h))Аффинное преобразование
Аффинное преобразование сохраняет параллельность и отношения расстояний — определяется 3 соответствиями точек (6 степеней свободы). warpAffine неявно использует прямое отображение через обратный поиск, поэтому M отображает src->dst, но внутри функция её инвертирует. Используйте borderMode=BORDER_REFLECT или BORDER_CONSTANT, чтобы управлять заполнением областей за границами.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# affine: parallel lines stay parallel (6 DOF)
src = np.float32([[50, 50], [200, 50], [50, 200]])
dst = np.float32([[10, 100], [200, 50], [100, 250]])
M = cv2.getAffineTransform(src, dst)
warped = cv2.warpAffine(img, M, (w, h))
# inverse mapping (destination -> source)
inv = cv2.invertAffineTransform(M)
# translation is a special affine
T = np.float32([[1, 0, 100], [0, 1, 50]]) # shift right 100, down 50
shifted = cv2.warpAffine(img, T, (w, h))
# black border is default; use borderMode for other fill
reflected = cv2.warpAffine(img, T, (w, h),
borderMode=cv2.BORDER_REFLECT)Перспективное преобразование
Перспектива (гомография) определяется 4 неколлинеарными парами точек — 8 степеней свободы. Это стандартное преобразование «сканера документов»: выберите 4 угла карточки или листа на фото и разверните в прямоугольник. getPerspectiveTransform требует ровно 4 точки; для переопределённой подгонки используйте cv2.findHomography с RANSAC.
import cv2
import numpy as np
img = cv2.imread("card.jpg")
h, w = img.shape[:2]
# 4 point correspondences define a perspective (homography)
src = np.float32([[73, 110], [320, 78], [380, 350], [40, 320]])
dst = np.float32([[0, 0], [w, 0], [w, h], [0, h]])
M = cv2.getPerspectiveTransform(src, dst)
warped = cv2.warpPerspective(img, M, (w, h))
# invert the homography to map back
M_inv = cv2.getPerspectiveTransform(dst, src)
restored = cv2.warpPerspective(warped, M_inv, (w, h))Отражение и зеркало
flip — дешёвая операция в памяти, гораздо быстрее warpAffine. Соглашение о знаке flipCode: положительное отражает по горизонтали, 0 — по вертикали, отрицательное — и так, и так. cv2.transpose меняет оси местами и иногда используется как быстрый поворот на 90° в сочетании с flip.
import cv2
img = cv2.imread("photo.jpg")
# flip(img, flipCode)
# 0 -> vertical flip (around x-axis) (upside-down)
# 1 -> horizontal flip (around y-axis) (mirror)
# -1 -> both (180° rotation equivalent)
v = cv2.flip(img, 0)
h = cv2.flip(img, 1)
both = cv2.flip(img, -1)
# transpose (swap x and y axes) — like a 90° rotation + flip
t = cv2.transpose(img)Remap (своё отображение)
remap — самое общее геометрич еское преобразование: масштабирование, поворот и даже исправление бочкообразных искажений объектива выражаются через remap. Всегда стройте карты векторизацией NumPy, а не циклами Python (версия с циклом выше приведена только для иллюстрации — она примерно в 100 раз медленнее). INTER_LINEAR — значение по умолчанию; для субпиксельной точности на краях используйте INTER_CUBIC.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# build coordinate maps: map_x, map_y say where each output pixel comes from
map_x = np.zeros((h, w), dtype=np.float32)
map_y = np.zeros((h, w), dtype=np.float32)
for y in range(h):
for x in range(w):
# mirror the image
map_x[y, x] = w - 1 - x
map_y[y, x] = y
remapped = cv2.remap(img, map_x, map_y, cv2.INTER_LINEAR)
# vectorized version (much faster) — wave distortion
xs, ys = np.meshgrid(np.arange(w), np.arange(h))
map_x = xs.astype(np.float32) + 10 * np.sin(ys / 20.0)
map_y = ys.astype(np.float32) + 10 * np.cos(xs / 20.0)
wave = cv2.remap(img, map_x, map_y, cv2.INTER_LINEAR,
borderMode=cv2.BORDER_REFLECT)Фильтрация изображений
Среднее размытие (box filter)
Среднее размытие — простейший низкочастотный фильтр: он заменяет каждый пиксель средним по окрестности. Ядра должны быть нечётными и положительными. Большие ядра размывают сильнее, но и быстрее уничтожают детали. Используйте его, когда нужны именно равномерные веса; для естественных изображений гауссово размытие почти всегда лучше.
import cv2
img = cv2.imread("photo.jpg")
# 3x3 box blur
blur3 = cv2.blur(img, (3, 3))
# larger kernel = more blur
blur9 = cv2.blur(img, (9, 9))
# boxFilter with normalized=False gives the sum (not average)
sum_ = cv2.boxFilter(img, -1, (5, 5), normalize=False)
# normalized=True is equivalent to cv2.blur
avg = cv2.boxFilter(img, -1, (5, 5), normalize=True)Гауссово размытие
Гауссово размытие — ядро сглаживания по умолчанию: оно взвешивает соседей по Гауссу и лучше сохраняет края, чем box-фильтр. Если передать ksize=(0,0) и sigmaX, OpenCV сам вычислит размер ядра. Гауссово размытие — обязательный предварительный шаг перед Canny, даунсэмплингом и лапласианом, чтобы под авить усиление шума.
import cv2
img = cv2.imread("photo.jpg")
# GaussianBlur(img, ksize, sigmaX)
g = cv2.GaussianBlur(img, (5, 5), 0)
# specifying sigma explicitly
g2 = cv2.GaussianBlur(img, (5, 5), sigmaX=1.5, sigmaY=1.5)
# odd kernel size required; (0, 0) auto-derives sigma from ksize
g3 = cv2.GaussianBlur(img, (0, 0), sigmaX=2.0)
# Gaussian is the standard pre-processing step before edge detection
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blurred, 50, 150)Медианное размытие
Медианное размытие — основной фильтр для шума «соль и перец» (импульсного): он заменяет каждый пиксель медианой окрестности, поэтому изолированные выбросы удаляются, а не размазываются. В отличие от гауссова, он хорошо сохраняет края. Размер ядра должен быть нечётным. Он медленнее гауссова и box-фильтра из-за сортировки.
import cv2
img = cv2.imread("noisy.jpg")
# median blur — great for salt-and-pepper noise
m = cv2.medianBlur(img, 5)
# larger kernel removes more noise but blurs edges
m2 = cv2.medianBlur(img, 7)
# compared to Gaussian on the same image
g = cv2.GaussianBlur(img, (5, 5), 0)Билатеральный фильтр
Билатеральная фильтрация сглаживает плоские области, сохраняя резкие края: это нелинейный фильтр, взвешивающий соседей И по пространственной близости, И по схожести цвета. Он гораздо медленнее гауссова (часто в 10 раз). Повторное применение — классический шаг предобработки для «мультяшного» эффекта; большие sigmaColor смешивают больше цветов.
import cv2
img = cv2.imread("photo.jpg")
# bilateralFilter(img, d, sigmaColor, sigmaSpace)
# d = neighborhood diameter
# sigmaColor = how much colors can differ and still blend
# sigmaSpace = how far pixels influence each other (spatial)
b = cv2.bilateralFilter(img, d=9, sigmaColor=75, sigmaSpace=75)
# strong edge-preserving smoothing (cartoon effect)
b_strong = cv2.bilateralFilter(img, d=15, sigmaColor=150, sigmaSpace=150)
# repeat several times for a "cartoon / oil painting" look
cartoon = img.copy()
for _ in range(7):
cartoon = cv2.bilateralFilter(cartoon, d=9, sigmaColor=75, sigmaSpace=75)Повышение резкости (ядро)
Ядра повышения резкости подчёркивают высокие частоты, но также усиливают шум, поэтому применяйте их после шумоподавления. Классическое ядро 3x3 для резкости суммируется в 1 (сохраняет яркость); сумма > 1 осветляет. Техника unsharp mask (вычитание размытой копии) более управляема и именно её используют большинство фоторедакторов.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# sharpening kernel: center boosts, neighbors subtracted
kernel = np.array([[ 0, -1, 0],
[-1, 5, -1],
[ 0, -1, 0]], dtype=np.float32)
sharp = cv2.filter2D(img, -1, kernel)
# stronger sharpening
kernel_strong = np.array([[-1, -1, -1],
[-1, 9, -1],
[-1, -1, -1]], dtype=np.float32)
sharp2 = cv2.filter2D(img, -1, kernel_strong)
# unsharp mask: image + (image - blurred) * amount
blur = cv2.GaussianBlur(img, (0, 0), 3)
unsharp = cv2.addWeighted(img, 1.5, blur, -0.5, 0)Своё ядро (filter2D)
filter2D применяет произвольное ядро корреляции — ddepth=-1 сохраняет глубину источника. Ядра могут быть float для отрицательных коэффициентов; если результат уходит в минус, переключите ddepth=cv2.CV_16S или CV_32F, затем вернитесь через convertScaleAbs. Разделимые ядра (внешнее произведение 1D-ядер) гораздо быстрее через sepFilter2D.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# emboss kernel
emboss = np.array([[-2, -1, 0],
[-1, 1, 1],
[ 0, 1, 2]], dtype=np.float32)
out = cv2.filter2D(img, -1, emboss)
# edge enhance (Laplacian-like)
edge = np.array([[ 0, 1, 0],
[ 1, -4, 1],
[ 0, 1, 0]], dtype=np.float32)
edges = cv2.filter2D(img, -1, edge)
# box blur done manually
box = np.ones((5, 5), dtype=np.float32) / 25.0
blurred = cv2.filter2D(img, -1, box)
# separable filter (Gaussian) — faster than 2D
kx = cv2.getGaussianKernel(5, 1.0) # 5x1
ky = cv2.getGaussianKernel(5, 1.0) # 5x1
g2d = kx @ ky.T # 5x5
out2 = cv2.filter2D(img, -1, g2d)Морфологические операции
Эрозия и дилатация
Эрозия сжимает области переднего плана (белые) и удаляет мелкие пятна шума; дилатация расширяет их и заполняет мелкие дыры. Форма ядра важна: RECT для общего применения, ELLIPSE для более круглых объектов, CROSS для утоньшения и соединения вдоль осей. iterations=N повторяет операцию N раз, что эквивалентно большему ядру.
import cv2
import numpy as np
img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
kernel = np.ones((5, 5), np.uint8)
# erosion: shrinks white regions (removes small noise)
eroded = cv2.erode(binary, kernel, iterations=1)
# dilation: grows white regions (fills small holes)
dilated = cv2.dilate(binary, kernel, iterations=1)
# custom kernel shapes
rect = cv2.getStructuringElement(cv2.MORPH_RECT, (5, 5))
cross = cv2.getStructuringElement(cv2.MORPH_CROSS, (5, 5))
ellipse = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))Открытие и закрытие
Открытие (эрозия→дилатация) удаляет мелкие яркие пятна, не меняя размер крупных объектов. Закрытие (дилатация→эрозия) заполняет мелкие тёмные дыры. Они идемпотентны: двукратное применение равно однократному. Классический паттерн шумоподавления — закрытие, затем открытие (или наоборот), чтобы справиться с обоими типами дефектов.
import cv2
import numpy as np
img = cv2.imread("noisy.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
kernel = np.ones((5, 5), np.uint8)
# opening = erode then dilate -> removes small foreground noise
opened = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
# closing = dilate then erode -> fills small holes in foreground
closed = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
# typical denoise pipeline: open then close
clean = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
clean = cv2.morphologyEx(clean, cv2.MORPH_OPEN, kernel)Морфологический градиент
Морфологический градиент (дилатация минус эрозия) даёт толстый контур границ объектов — полезно как быстрый детектор краёв или маска для сегментации. В отличие от Canny он даёт залитые широкие края, поэтому хорош для выделения областей, а не для измерения точного положения краёв.
import cv2
import numpy as np
img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
kernel = np.ones((5, 5), np.uint8)
# gradient = dilation - erosion -> outlines of objects
gradient = cv2.morphologyEx(binary, cv2.MORPH_GRADIENT, kernel)
# on a grayscale image (works too)
gray_grad = cv2.morphologyEx(img, cv2.MORPH_GRADIENT, kernel)Top Hat и Black Hat
Top-hat извлекает мелкие яркие структуры меньше ядра (например, текст на тёмном документе); black-hat — мелкие тёмные структуры. Вместе их используют для извлечения теней и бликов и как быстрый корректор неравномерного освещения (приём деления на фон распространён в сканерах документов).
import cv2
import numpy as np
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
kernel = np.ones((15, 15), np.uint8)
# top hat = image - opening -> small bright features on dark bg
tophat = cv2.morphologyEx(img, cv2.MORPH_TOPHAT, kernel)
# black hat = closing - image -> small dark features on bright bg
blackhat = cv2.morphologyEx(img, cv2.MORPH_BLACKHAT, kernel)
# use case: correct uneven illumination
# background = large closing; divide image by background
bg = cv2.morphologyEx(img, cv2.MORPH_CLOSE, kernel)
corrected = cv2.divide(img, bg, scale=255)Скелетизация
Морфологическая скелетизация утоньшает бинарную фигуру до срединной оси шириной 1 пиксель — полезно для OCR, отпечатков пальцев и анализа сосудов. Итеративный цикл «эрозия — вычитание — открытие» выполняется до опустошения изображения. Для продакшена medial_axis или thinning из scikit-image быстрее и дают чище результат.
import cv2
import numpy as np
img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, img = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
# skeleton via iterative morphological opening
kernel = np.ones((3, 3), np.uint8)
skeleton = np.zeros_like(img)
while True:
eroded = cv2.erode(img, kernel)
opened = cv2.morphologyEx(eroded, cv2.MORPH_OPEN, kernel)
temp = cv2.subtract(eroded, opened)
skeleton = cv2.bitwise_or(skeleton, temp)
img = eroded
if cv2.countNonZero(img) == 0:
breakHit-or-Miss
Hit-or-miss — морфологический сопоставитель шаблонов: он находит точные конфигурации пикселей переднего и заднего плана, полезен для обнаружения конкретных форм вроде углов или T-образных соединений. Ядро использует 1 для требуемого переднего плана, -1 для требуемого фона, 0 для «не важно». Метод нишевый, но незаменим для точного поиска шаблонов.
import cv2
import numpy as np
img = cv2.imread("pattern.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
# hit-or-miss finds exact patterns
# kernel encodes foreground (1), background (-1), don't-care (0)
kernel = np.array([[ 0, 1, -1],
[ 1, -1, -1],
[ 1, 1, 0]], dtype=np.int32)
hits = cv2.morphologyEx(binary, cv2.MORPH_HITMISS, kernel)
# count matching locations
ys, xs = np.where(hits > 0)
print(f"found {len(xs)} matches")Обнаружение краёв
Детектор краёв Canny
Canny — самый используемый детектор краёв: гауссово сглаживание → градиенты Собеля → подавление немаксимумов → гистерезис (два порога). Пиксели выше высокого порога — края; между низким и высоким — края, только если связаны с сильным краем. Приём авто-порога (медиана × 0.7/1.3) хорошо работает для разнообразных изображений.
import cv2
img = cv2.imread("photo.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
# Canny(image, threshold1, threshold2, apertureSize, L2gradient)
edges = cv2.Canny(blurred, 50, 150)
# auto-tuned thresholds from the median intensity
v = np.median(blurred)
lower = int(max(0, 0.7 * v))
upper = int(min(255, 1.3 * v))
auto = cv2.Canny(blurred, lower, upper)
# L2 gradient (more accurate, slower)
edges_l2 = cv2.Canny(blurred, 50, 150, L2gradient=True)Оператор Собеля
Sobel вычисляет первую производную — используйте ddepth=cv2.CV_64F (или CV_16S), чтобы захватить отрицательные градиенты, иначе переполнение uint8 делает переходы от тёмного к светлому невидимыми. ksize=3 стандартен; ksize=5 даёт более гладкие, но широкие края. Магнитуда (sqrt(sx²+sy²)) — основа Canny и многих детекторов признаков.
import cv2
import numpy as np
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# Sobel x (vertical edges)
sx = cv2.Sobel(img, cv2.CV_64F, 1, 0, ksize=3)
# Sobel y (horizontal edges)
sy = cv2.Sobel(img, cv2.CV_64F, 0, 1, ksize=3)
# gradient magnitude
mag = np.sqrt(sx**2 + sy**2)
mag = np.uint8(255 * mag / mag.max())
# gradient direction (for non-max suppression)
angle = np.arctan2(sy, sx)
# convert back to visible uint8
sx_abs = cv2.convertScaleAbs(sx)
sy_abs = cv2.convertScaleAbs(sy)Лапласиан
Лапласиан — вторая производная, очень чувствителен к шуму, поэтому всегда сначала размывайте. Он обнаруживает переходы через ноль (смену знака), давая тонкие точные края без направления. Чаще всего используется в детекторе краёв Марра-Хилдрета и как вход канала 'L' при повышении резкости (unsharp mask). Используйте CV_64F, потому что вторая производная сильно уходит в минус.
import cv2
import numpy as np
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
blurred = cv2.GaussianBlur(img, (3, 3), 0)
# Laplacian: second derivative in both directions
lap = cv2.Laplacian(blurred, cv2.CV_64F)
lap_abs = cv2.convertScaleAbs(lap)
# zero-crossing detection (sharper edges)
# Manual Laplacian kernel
kernel = np.array([[0, 1, 0],
[1, -4, 1],
[0, 1, 0]], dtype=np.float32)
edges = cv2.filter2D(blurred, -1, kernel)Фильтр Шарра
Scharr — вариант Собеля для окон 3x3: когда нужно маленькое ядро, он даёт более точное направление градиента, чем Sobel ksize=3. Для больших ядер (5x5, 7x7) Sobel подходит. cv2.Sobel с ksize=-1 эквивалентен Scharr. Scharr предпочтителен, когда важно направление градиента (HOG, ориентация краёв).
import cv2
import numpy as np
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# Scharr: a Sobel variant optimized for 3x3 kernels
# better rotational symmetry than 3x3 Sobel
sx = cv2.Scharr(img, cv2.CV_64F, 1, 0)
sy = cv2.Scharr(img, cv2.CV_64F, 0, 1)
mag = cv2.magnitude(sx, sy)
mag_u8 = cv2.convertScaleAbs(mag)
# equivalent to Sobel with ksize=-1
sx2 = cv2.Sobel(img, cv2.CV_64F, 1, 0, ksize=-1)Конвейер обнаружения краёв
Конвейер «оттенки серого → шумоподавление → Canny → дилатация → findContours» покрывает огромную долю практических задач с краями. Дилатация перед поиском контуров замыкает разрывы краёв, которые иначе разбили бы один объект на множество. Настройка порогов Canny и размера ядра шумоподавления — здесь уходит большая часть инженерных усилий.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# 1. grayscale
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# 2. denoise (Gaussian or bilateral)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
# 3. auto-thresholded Canny
v = np.median(blurred)
edges = cv2.Canny(blurred, int(0.7 * v), int(1.3 * v))
# 4. dilate to close gaps, then find contours
edges = cv2.dilate(edges, np.ones((3, 3), np.uint8), iterations=1)
contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
# 5. filter by area
out = img.copy()
for c in contours:
if cv2.contourArea(c) > 100:
cv2.drawContours(out, [c], -1, (0, 255, 0), 2)
cv2.imshow("edges", edges)
cv2.imshow("contours", out)
cv2.waitKey(0)Контуры
Поиск контуров
findContours изменяет исходное изображение в OpenCV 3.x — передавайте копию, если бинарное изображение нужно после. RETR_EXTERNAL возвращает только внешние контуры (быстрее всего); RETR_TREE даёт полную иерархию для вложенных фигур (дыры внутри объектов). CHAIN_APPROX_SIMPLE отбрасывает избыточные точки на прямых линиях, экономя память.
import cv2
img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
# findContours(image, mode, method)
# mode: RETR_EXTERNAL (outer only), RETR_LIST, RETR_TREE, RETR_CCOMP
# method: CHAIN_APPROX_SIMPLE compresses horizontal/vertical/diagonal segments
contours, hierarchy = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
print(f"found {len(contours)} contours")
# hierarchy is shape (1, N, 4): [next, prev, child, parent]
# OpenCV 3 returns (image, contours, hierarchy)
# OpenCV 4 returns (contours, hierarchy)Рисование контуров
drawContours(image, contours, contourIdx, color, thickness): contourIdx=-1 рисует все, конкретный индекс — один. thickness=-1 заливает контур. Рисование на пустом изображении — стандартный способ построить маску контура для последующих операций вроде среднего цвета или гистограммы по маске.
import cv2
img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
# draw all contours (-1), color, thickness
cv2.drawContours(img, contours, -1, (0, 255, 0), 2)
# draw a single contour by index
cv2.drawContours(img, contours, 0, (0, 0, 255), 3)
# filled contour (thickness = -1)
cv2.drawContours(img, contours, -1, (255, 0, 0), -1)
# draw on a blank canvas (mask)
mask = np.zeros_like(gray)
cv2.drawContours(mask, contours, -1, 255, -1)Свойства контуров
contourArea измеряется в пикселях и игнорирует дыры (для чистой площади используйте контур с иерархией RETR_CCOMP). Словарь моментов даёт центроид (m10/m00, m01/m00) — защищайтесь от деления на ноль, если m00 равно 0 (вырожденные контуры). Соотношение сторон и extent — простейшие дескрипторы формы для классификации.
import cv2
img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
area = cv2.contourArea(c) # area in pixels
peri = cv2.arcLength(c, True) # perimeter (closed=True)
M = cv2.moments(c) # spatial moments
cx = int(M['m10'] / M['m00']) # centroid x
cy = int(M['m01'] / M['m00']) # centroid y
# bounding box
x, y, w, h = cv2.boundingRect(c)
aspect = w / float(h) # aspect ratio
extent = area / float(w * h) # filled area ratio
print(f"area={area:.0f} peri={peri:.1f} center=({cx},{cy}) aspect={aspect:.2f}")Ограничивающие прямоугольники
boundingRect даёт выровненный по осям прямоугольник (быстро, просто); minAreaRect — наименьший повёрнутый прямоугольник (полезен для измерения истинной ориентации и размера объекта). boxPoints превращает повёрнутый прямоугольник в 4 угловые точки, которые можно передать в drawContours. minEnclosingCircle — наименьшая окружность, содержащая контур.
import cv2
img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
# axis-aligned bounding rectangle
x, y, w, h = cv2.boundingRect(c)
cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 2)
# minimum area (rotated) rectangle
rect = cv2.minAreaRect(c) # ((cx, cy), (w, h), angle)
box = cv2.boxPoints(rect) # 4 corner points
box = np.int0(box)
cv2.drawContours(img, [box], 0, (0, 0, 255), 2)
# minimum enclosing circle
(cx, cy), r = cv2.minEnclosingCircle(c)
cv2.circle(img, (int(cx), int(cy)), int(r), (255, 0, 0), 2)Аппроксимация контуров
approxPolyDP упрощает контур до многоугольника с меньшим числом вершин алгоритмом Дугласа-Пекера. epsilon (обычно 1–5% периметра) управляет допуском: меньше — больше деталей. Подсчёт вершин — классический самодельный классификатор форм: треугольник=3, прямоугольник=4, круг=много.
import cv2
img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
peri = cv2.arcLength(c, True)
# approxPolyDP: simplify the contour to fewer vertices
eps = 0.04 * peri # 4% of perimeter
approx = cv2.approxPolyDP(c, eps, True)
n = len(approx)
if n == 3:
label = "triangle"
elif n == 4:
label = "rectangle"
elif n == 5:
label = "pentagon"
else:
label = f"{n}-gon"
cv2.drawContours(img, [approx], -1, (0, 255, 0), 2)
cv2.putText(img, label, tuple(approx[0][0]),
cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 255), 2)Выпуклая оболочка и дефекты
Выпуклая оболочка — наименьшая выпуклая фигура, содержащая контур: полезна для измерения компактности объекта и обнаружения рук и пальцев через дефекты выпуклости. Глубина каждого дефекта показывает, насколько контур «вдаётся» внутрь относительно оболочки; глубокие дефекты на силуэте руки обычно соответствуют промежуткам между пальцами.
import cv2
img = cv2.imread("hand.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
c = max(contours, key=cv2.contourArea)
# convex hull (smallest convex polygon enclosing the contour)
hull = cv2.convexHull(c)
cv2.drawContours(img, [hull], -1, (0, 255, 0), 2)
# convexity defects (gaps between contour and hull) — needs returnPoints=False
hull_idx = cv2.convexHull(c, returnPoints=False)
defects = cv2.convexityDefects(c, hull_idx)
# defects[i] = (start, end, far, depth) — depth in 1/256 of peri
# is the contour convex?
is_convex = cv2.isContourConvex(c)Пороговая бинаризация
Базовый порог
THRESH_BINARY: выше->255, ниже->0. THRESH_TRUNC: выше->ограничено порогом, ниже->без изменений. THRESH_TOZERO: выше->без изменений, ниже->0. Возвращаемый ret для обычной бинаризации равен входному порогу, но становится осмысленным для Otsu/Triangle. Выбирайте тип по тому, как нужно обрабатывать пиксели вне диапазона.
import cv2
img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)
# threshold(src, thresh, maxval, type)
# returns (retval, binary_image)
ret, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
# threshold types
_, inv = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY_INV)
_, trunc = cv2.threshold(img, 127, 255, cv2.THRESH_TRUNC)
_, tozero = cv2.threshold(img, 127, 255, cv2.THRESH_TOZERO)
_, tozero_inv = cv2.threshold(img, 127, 255, cv2.THRESH_TOZERO_INV)
# ret is the threshold actually used (useful with Otsu)Адаптивный порог
Адаптивная бинаризация вычисляет отдельный порог для каждого пикселя по его локальной окрестности — необходимо для изображений с неравномерным освещением (например, фотографий документов). blockSize должен быть нечётным (обычно 11–31) и больше размера дет алей. C вычитает константу из локального среднего; увеличивайте её, чтобы подавить низкоконтрастный шум.
import cv2
img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)
img = cv2.medianBlur(img, 5)
# adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C)
# adaptiveMethod:
# ADAPTIVE_THRESH_MEAN_C -> mean of neighborhood minus C
# ADAPTIVE_THRESH_GAUSSIAN_C -> weighted mean minus C
adap_mean = cv2.adaptiveThreshold(img, 255,
cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY, 11, 2)
adap_gauss = cv2.adaptiveThreshold(img, 255,
cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2)Метод Оцу
Метод Оцу находит оптимальный глобальный порог, максимизируя дисперсию между классами переднего и заднего плана: передайте thresh=0 и добавьте флаг THRESH_OTSU. Всегда сначала размывайте: Оцу чувствителен к шуму гистограммы. Метод Triangle лучше работает на изображениях с одним доминирующим пиком (например, микроскопия). Возвращаемый ret — вычисленный порог.
import cv2
img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)
blurred = cv2.GaussianBlur(img, (5, 5), 0)
# Otsu: automatically picks the threshold that maximizes between-class variance
ret, otsu = cv2.threshold(blurred, 0, 255,
cv2.THRESH_BINARY + cv2.THRESH_OTSU)
print(f"Otsu threshold: {ret}")
# Triangle method (good for skewed histograms / single peak)
ret_t, tri = cv2.threshold(blurred, 0, 255,
cv2.THRESH_BINARY + cv2.THRESH_TRIANGLE)
print(f"Triangle threshold: {ret_t}")Цветовой порог (inRange)
inRange — стандартный инструмент цветовой сегментации: сначала переведите в HSV, потому что он отделяет цвет (тон) от яркости, делая пороги устойчивыми к изменению освещения. Красный тон заворачивается вокруг 0/180, поэтому нужны две маски, объединё нные через OR. Всегда размывайте перед inRange, чтобы уменьшить пятна шума в маске.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
# detect a range of green pixels
lower = np.array([35, 50, 50])
upper = np.array([85, 255, 255])
mask = cv2.inRange(hsv, lower, upper)
# apply mask to the original
result = cv2.bitwise_and(img, img, mask=mask)
# hue wraps around for red (0-10 and 170-180)
mask1 = cv2.inRange(hsv, np.array([0, 50, 50]), np.array([10, 255, 255]))
mask2 = cv2.inRange(hsv, np.array([170, 50, 50]), np.array([180, 255, 255]))
red_mask = cv2.bitwise_or(mask1, mask2)Конвейер бинаризации
Конвейер «шумоподавление → порог → морфология» решает большинство задач бинаризации. Выбирайте Otsu для равномерного освещения, адаптивный — для неравномерного. Морфологическое «закрытие, затем открытие» убирает и внутренние дыры, и внешние пятна. Всегда проверяйте бинарную маску: параметры порога почти всегда зависят от изображения и требуют подстройки под набор данных.
import cv2
import numpy as np
img = cv2.imread("doc.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# 1. denoise
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
# 2. choose a method
# - flat lighting -> Otsu
# - uneven lighting -> adaptive
# - document scan -> adaptive Gaussian
if lighting == "flat":
_, binary = cv2.threshold(blurred, 0, 255,
cv2.THRESH_BINARY + cv2.THRESH_OTSU)
else:
binary = cv2.adaptiveThreshold(blurred, 255,
cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 21, 5)
# 3. morphology cleanup
kernel = np.ones((3, 3), np.uint8)
binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
binary = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)Бинаризация для OCR
Для OCR адаптивный гауссов почти всегда обходит глобальный Otsu на сфотографированных документах из-за неравномерного освещения. Согласуйте blockSize с высотой символа (эмпирическое правило: 1–2× ширины штриха × 4). Большинство OCR-движков (Tesseract) предпочитают чёрный текст на белом фоне — инвертируйте, если ваша бинаризация даёт обратное.
import cv2
img = cv2.imread("text.png", cv2.IMREAD_GRAYSCALE)
# adaptive Gaussian with a block size matched to character height
# (e.g. char ~25 px -> blockSize ~31)
binary = cv2.adaptiveThreshold(img, 255,
cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, 10)
# invert if needed (OCR often prefers black-on-white)
binary_inv = cv2.bitwise_not(binary)
# Otsu on a preprocessed image as an alternative
blur = cv2.GaussianBlur(img, (3, 3), 0)
_, otsu = cv2.threshold(blur, 0, 255,
cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)Цветовые пространства
BGR / RGB / Gray
OpenCV по умолчанию читает изображения как BGR; большинство других библиотек (matplotlib, PIL, scikit-image) используют RGB. Забыть cvtColor — самая частая причина изображений с «перепутанными красным и синим». Преобразова ние в оттенки серого использует перцептивные веса (Y = 0.299R + 0.587G + 0.114B), а не простое среднее.
import cv2
bgr = cv2.imread("photo.jpg") # OpenCV default: BGR
# BGR -> RGB (for matplotlib, PIL, etc.)
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
# BGR -> grayscale (luminance-weighted)
gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
# RGB -> BGR (reverse)
bgr2 = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
# grayscale -> BGR (replicates channel, color image with no color)
bgr_from_gray = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)BGR в HSV
HSV в OpenCV использует H в диапазоне 0–179 (а не 0–360), чтобы уместиться в uint8, — частый источник ошибок в 2 раза при переносе кода из других библиотек. S и V — 0–255. HSV — основное пространство для цветовой сегментации, потому что тон примерно инвариантен к изменению яркости; используйте его для отслеживания объектов по цвету.
import cv2
import numpy as np
bgr = cv2.imread("photo.jpg")
hsv = cv2.cvtColor(bgr, cv2.COLOR_BGR2HSV)
# split channels
h, s, v = cv2.split(hsv)
# HSV ranges in OpenCV: H: 0-179, S: 0-255, V: 0-255
# (H is halved so it fits in 8-bit — full hue circle is 0-360)
print(h.max(), s.max(), v.max()) # 179 255 255
# back to BGR
bgr2 = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)BGR в LAB
CIELAB приближает человеческое восприятие: одинаковые числовые изменения выглядят примерно одинаково различными, поэтому его используют для метрик цветовых различий (ΔE). Канал L кодирует только светлоту, поэтому правка L — самый чистый способ осветлить изображение без сдвига цветов. LAB в OpenCV использует 0–255 для всех каналов, а не стандартные 0–100 для L.
import cv2
bgr = cv2.imread("photo.jpg")
# BGR -> LAB (perceptually uniform color space)
lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
L, A, B = cv2.split(lab)
# L: lightness (0-255), A: green<->red, B: blue<->yellow
# useful for separating luminance from color
# LAB is great for color-difference metrics (delta-E)
# and for editing lightness without affecting color
import numpy as np
lab_bright = lab.copy()
lab_bright[:, :, 0] = np.clip(lab_bright[:, :, 0].astype(int) + 30, 0, 255)
bgr_bright = cv2.cvtColor(lab_bright, cv2.COLOR_LAB2BGR)Отслеживание по цвету (HSV)
Отслеживание по HSV — простейший трекер объектов: выберите диапазон тона, примените порог, найдите наибольшее пятно. Он ломается при плохом освещении (низкая насыщенность), на фоне похожего цвета и на отражающих поверхностях. Для устойчивого отслеживания сочетайте с camshift/meanshift (обратная проекция гистограммы тона) или фильтром Калмана для сглаживания движения.
import cv2
import numpy as np
cap = cv2.VideoCapture(0)
while True:
ret, frame = cap.read()
if not ret:
break
hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
# track a blue object
lower = np.array([100, 80, 80])
upper = np.array([130, 255, 255])
mask = cv2.inRange(hsv, lower, upper)
# find the largest blob
contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
if contours:
c = max(contours, key=cv2.contourArea)
if cv2.contourArea(c) > 500:
(x, y), r = cv2.minEnclosingCircle(c)
cv2.circle(frame, (int(x), int(y)), int(r), (0, 255, 255), 2)
cv2.imshow("frame", frame)
cv2.imshow("mask", mask)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()Разделение и слияние каналов
split/merge удобны, но медленнее индексации NumPy: img[:, :, 0] — синий канал, и изменять его быстрее, чем split. Всегда передавайте каналы в merge в правильном порядке для целевого цветового пространства. Приём «обнулить два канала» — классический способ визуализировать вклад одного цветового канала.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# split into B, G, R channels (each is a 2-D array)
b, g, r = cv2.split(img)
# merge channels back (order matters!)
merged = cv2.merge([b, g, r])
# zero out one channel to visualize
zeros = np.zeros_like(b)
blue_only = cv2.merge([b, zeros, zeros])
green_only = cv2.merge([zeros, g, zeros])
red_only = cv2.merge([zeros, zeros, r])
# swap channels (e.g. fake RGB->BGR by swapping R and B)
swapped = cv2.merge([r, g, b])Другие цветовые пространства
YCrCb отделяет яркость (Y) от цветности (Cr, Cb) — основа сжатия JPEG и MPEG, которое отбрасывает детали цветности, потому что люди менее чувствительны к цвету, чем к яркости. HLS отличается от HSV тем, что белый находится при L=1 независимо от насыщенности, что делает HLS лучше для некоторых эффектов затенения. Выбирайте пространство, в котором ваша операция инвариантна к тому, что вам не важно.
import cv2
bgr = cv2.imread("photo.jpg")
# YCrCb (used in JPEG compression)
ycrcb = cv2.cvtColor(bgr, cv2.COLOR_BGR2YCrCb)
# HLS (Hue, Lightness, Saturation — alternative to HSV)
hls = cv2.cvtColor(bgr, cv2.COLOR_BGR2HLS)
# YUV (used in video encoding)
yuv = cv2.cvtColor(bgr, cv2.COLOR_BGR2YUV)
# grayscale -> all spaces start from BGR, so chain conversions
gray_from_ycrcb = cv2.cvtColor(ycrcb, cv2.COLOR_YCrCb2BGR)
gray = cv2.cvtColor(gray_from_ycrcb, cv2.COLOR_BGR2GRAY)Гистограммы
Вычисление гистограммы
calcHist принимает список изображений, список каналов, необязательную маску (None = всё изображение), число корзин и диапазон значений. Для многомерных гистограмм (например, 2-D тон-насыщенность) передайте два канала и два размера корзин — это используется в обратной проекции гистограммы для отслеживания цвета. Гистограмма каждого канала вычисляется независимо.
import cv2
import numpy as np
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# calcHist(images, channels, mask, histSize, ranges)
hist = cv2.calcHist([img], [0], None, [256], [0, 256])
print(hist.shape) # (256, 1)
# normalize to 0-1
hist /= hist.sum()
# multi-channel histogram (color)
bgr = cv2.imread("photo.jpg")
colors = ('b', 'g', 'r')
for i, col in enumerate(colors):
h = cv2.calcHist([bgr], [i], None, [256], [0, 256])Построение гистограммы
Matplotlib — самый простой способ визуализировать гистограммы, но не забудьте перевести BGR в RGB для цветов легенды, иначе цвета на графике не совпадут с подписями каналов. Гистограмма, смещённая влево, означает тёмное изображение, вправо — светлое; узкий пик говорит о низ ком контрасте. Используйте это для диагностики экспозиции и баланса белого.
import cv2
import numpy as np
import matplotlib.pyplot as plt
img = cv2.imread("photo.jpg")
colors = ('b', 'g', 'r')
for i, col in enumerate(colors):
hist = cv2.calcHist([img], [i], None, [256], [0, 256])
plt.plot(hist, color=col)
plt.xlim([0, 256])
plt.title("Color Histogram")
plt.xlabel("Pixel value")
plt.ylabel("Frequency")
plt.show()Эквализация гистограммы
Эквализация гистограммы растягивает интенсивности пикселей на весь диапазон 0–255 — отлично для низкоконтрастных изображений, но может выбить блики и усилить шум. НИКОГДА не эквализируйте все три канала BGR напрямую: это сдвигает цвета. Всегда переводите в пространство яркость/цветность (YCrCb, LAB, HSV), эквализируйте яркость и конвертируйте обратно.
import cv2
img = cv2.imread("dark.jpg", cv2.IMREAD_GRAYSCALE)
# global histogram equalization
eq = cv2.equalizeHist(img)
# equalization on color images: convert to YCrCb, equalize Y only
bgr = cv2.imread("color.jpg")
ycrcb = cv2.cvtColor(bgr, cv2.COLOR_BGR2YCrCb)
ycrcb[:, :, 0] = cv2.equalizeHist(ycrcb[:, :, 0])
eq_color = cv2.cvtColor(ycrcb, cv2.COLOR_YCrCb2BGR)CLAHE (адаптивная эквализация)
CLAHE — продакшен-альтернатива глобальной эквализации: она работает по небольшим тайлам, поэтому справляется с неравномерным освещением, а clipLimit ограничивает усиление контраста, чтобы не раздувать шум. tileGridSize 8x8 — значение по умолчанию; меньшие тайлы дают больше локальной адаптации. Основной выбор для медицинской визуализации и улучшения документов.
import cv2
img = cv2.imread("dark.jpg", cv2.IMREAD_GRAYSCALE)
# CLAHE: Contrast Limited Adaptive Histogram Equalization
# equalizes small tiles, limiting amplification of noise
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
enhanced = clahe.apply(img)
# on color: equalize the L channel of LAB
bgr = cv2.imread("color.jpg")
lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
lab[:, :, 0] = clahe.apply(lab[:, :, 0])
enhanced_color = cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)Обратная проекция гистограммы
Обратная проекция гистограммы отвечает на вопрос «где пиксели похожи на цветовое распределение моего ROI?». Постройте 2-D гистограмму тон-насыщенность по образцу, затем спроецируйте обратно на целевое изображение, получив карту вероятностей. Это основа отслеживания meanShift/camShift — гораздо устойчивее фиксированного диапазона HSV, потому что учит фактическое цветовое распределение цели.
import cv2
import numpy as np
img = cv2.imread("scene.jpg")
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
# take a small ROI of the target color (the object to track)
roi = hsv[100:150, 100:150]
roi_hist = cv2.calcHist([roi], [0, 1], None, [180, 256], [0, 180, 0, 256])
cv2.normalize(roi_hist, roi_hist, 0, 255, cv2.NORM_MINMAX)
# backproject: each pixel = probability of belonging to the ROI's color
backproj = cv2.calcBackProject([hsv], [0, 1], roi_hist, [0, 180, 0, 256], 1)
# denoise and threshold
disc = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
backproj = cv2.filter2D(backproj, -1, disc)
_, mask = cv2.threshold(backproj, 50, 255, cv2.THRESH_BINARY)
result = cv2.bitwise_and(img, img, mask=mask)Детекция признаков
Детектор углов Харриса
Харрис обнаруживает углы, проверяя, вызывает ли сдвиг небольшого окна в любом направлении сильное изменение интенсивности: углы меняются во всех направлениях, края — в одном, плоские области — ни в одном. Выход — карта отклика углов; порог задавайте относительно максимума (например, 0.01 * max). blockSize — окрестность для вычисления структурного тензора.
import cv2
import numpy as np
img = cv2.imread("chessboard.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# cornerHarris(gray, blockSize, ksize, k)
# blockSize: neighborhood for corner detection
# ksize: Sobel aperture (3, 5, 7)
# k: Harris free parameter (0.04 - 0.06)
dst = cv2.cornerHarris(gray, 2, 3, 0.04)
# dilate to mark corners
dst = cv2.dilate(dst, None)
# threshold and mark in red
img[dst > 0.01 * dst.max()] = [0, 0, 255]Shi-Tomasi (goodFeaturesToTrack)
Shi-Tomasi улучшает Харриса, используя min(eigenvalue1, eigenvalue2) как оценку, что даёт более стабильные углы для отслеживания. maxCorners ограничивает количество; qualityLevel — доля от самого сильного отклика (0.01 = 1% лучшего); minDistance обеспечивает прос транственное разделение найденных углов. Это стандартный вход для трекера оптического потока Лукаса-Канаде.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# goodFeaturesToTrack returns the N strongest corners
corners = cv2.goodFeaturesToTrack(gray, maxCorners=100,
qualityLevel=0.01,
minDistance=10)
corners = np.int0(corners)
for c in corners:
x, y = c.ravel()
cv2.circle(img, (x, y), 3, (0, 0, 255), -1)SIFT (масштабно-инвариантные признаки)
SIFT находит масштабно- и поворотно-инвариантные ключевые точки и 128-мерный дескриптор для каждой — устойчив к освещению, точке обзора и частичному перекрытию. Годами был запатентован, но стал свободным в OpenCV 4.4. Используйте SIFT для высокоточной стыковки, где скорость вторична. DRAW_RICH_KEYPOINTS рисует масштаб и ориентацию каждой ключевой точки.
import cv2
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# SIFT was patented; free since OpenCV 4.4 (contrib not required)
sift = cv2.SIFT_create()
# detect keypoints
kp = sift.detect(img, None)
# detect and compute descriptors
kp, des = sift.detectAndCompute(img, None)
print(len(kp), des.shape) # N, (N, 128)
# draw keypoints
out = cv2.drawKeypoints(img, kp, None,
flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS)ORB (FAST + BRIEF)
ORB сочетает детектор ключевых точек FAST с дескриптором BRIEF — оба без патентов и примерно в 10 раз быстрее SIFT, что делает ORB стандартом для сопоставления в реальном времени на мобильных и встраиваемых устройствах. Дескрипторы бинарные (32 байта против 128 float у SIFT), поэтому сопоставление использует расстояние Хэмминга. Немного менее устойч ив к масштабу и повороту, чем SIFT, но отличен за свою цену.
import cv2
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# ORB: free, fast alternative to SIFT
orb = cv2.ORB_create(nfeatures=1000)
kp, des = orb.detectAndCompute(img, None)
print(len(kp), des.shape) # N, (N, 32) — binary descriptors
# draw keypoints
out = cv2.drawKeypoints(img, kp, None, color=(0, 255, 0),
flags=0)
# FAST alone (detector only, no descriptor)
fast = cv2.FastFeatureDetector_create(threshold=20)
kp = fast.detect(img, None)Детектор FAST
FAST проверяет, есть ли на окружности из 16 пикселей вокруг кандидата N подряд идущих пикселей все ярче или все темнее центра, — крайне быстро благодаря короткому замыканию. Он возвращает только ключевые точки без дескрипторов (для дескрипторов используйте BRIEF или ORB). Ниже порог — больше (и шумнее) углов; подавление немаксимумов убирает дубликаты в локальных максимумах.
import cv2
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# FAST: speed-optimized corner detector (detector only)
fast = cv2.FastFeatureDetector_create(threshold=20,
nonmaxSuppression=True)
kp = fast.detect(img, None)
print(f"{len(kp)} keypoints")
# tune the threshold
fast.setThreshold(30)
print(f"threshold is now {fast.getThreshold()}")
# turn off non-max suppression to get more (clustered) corners
fast.setNonmaxSuppression(False)
kp_all = fast.detect(img, None)MSER (максимально стабильные экстремальные области)
MSER находит области, стабильные в диапазоне порогов интенсивности, — идеально для детекции текста (буквы похожи на пятна), номерных знаков и текста на сцене. Он хорошо справляется с неравномерным освещением, потому что каждая область обнаруживается при своём пороге. Фильтруйте результаты по соотношению сторон и размеру, чтобы убрать очевидно не текстовые области.
import cv2
img = cv2.imread("text.jpg", cv2.IMREAD_GRAYSCALE)
# MSER: detects stable connected regions across thresholds
mser = cv2.MSER_create()
regions, _ = mser.detectRegions(img)
# regions is a list of point arrays
out = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
for pts in regions:
x, y, w, h = cv2.boundingRect(pts)
if 5 < h < 50: # filter by likely text size
cv2.rectangle(out, (x, y), (x+w, y+h), (0, 255, 0), 1)Сопоставление признаков
Полный перебор (brute force)
Brute-force сопоставление перебирает каждую пару дескрипторов — точно, но O(N*M). Для бинарных дескрипторов ORB используйте NORM_HAMMING; для float-дескрипторов SIFT/SURF — NORM_L2. crossCheck=True оставляет только взаимно лучшие совпадения (лучшее у A — B, и наоборот), что убирает много ложных срабатываний. У каждого совпадения есть .distance — меньше лучше.
import cv2
img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
orb = cv2.ORB_create()
kp1, des1 = orb.detectAndCompute(img1, None)
kp2, des2 = orb.detectAndCompute(img2, None)
# for ORB (binary descriptors) use Hamming distance
bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)
matches = bf.match(des1, des2)
# sort by distance (best first)
matches = sorted(matches, key=lambda m: m.distance)
# draw top 20
out = cv2.drawMatches(img1, kp1, img2, kp2, matches[:20], None,
flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS)Сопоставление FLANN
FLANN (Fast Library for Approximate Nearest Neighbors) строит KD-дерево (для SIFT/SURF) или LSH (для ORB), чтобы находить приближённ ые совпадения, — гораздо быстрее полного перебора на больших наборах дескрипторов ценой случайных пропусков. Параметры trees и checks обменивают точность на скорость. Используйте FLANN при тысячах признаков; для малых наборов достаточно brute-force.
import cv2
import numpy as np
img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)
# FLANN parameters for SIFT (float descriptors)
FLANN_INDEX_KDTREE = 1
index_params = dict(algorithm=FLANN_INDEX_KDTREE, trees=5)
search_params = dict(checks=50)
flann = cv2.FlannBasedMatcher(index_params, search_params)
matches = flann.knnMatch(des1, des2, k=2)KNN-сопоставление и ratio test
Ratio test Лоу — стандартный фильтр сопоставления признаков: оставляйте совпадение, только если лучшее значительно ближе второго (типичный порог 0.7–0.8). Интуиция: если оба кандидата одинаково близки, совпадение неоднозначно и, вероятно, неверно. Один этот тест убирает подавляющее большинство ложных срабатываний.
import cv2
img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)
bf = cv2.BFMatcher(cv2.NORM_L2)
matches = bf.knnMatch(des1, des2, k=2) # 2 nearest neighbors
# Lowe's ratio test: keep only unambiguous matches
good = []
for m, n in matches:
if m.distance < 0.75 * n.distance:
good.append(m)
out = cv2.drawMatches(img1, kp1, img2, kp2, good, None,
flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS)Гомография (RANSAC)
findHomography с RANSAC вычисляет перспективное преобразование, отображающее src в dst, игнорируя выбросы: маска инлайеров показывает, какие совпадения согласуются с моделью. Порог репроекции (5.0) задаётся в пикселях; меньше — строже. Нужно минимум 4 хороших совпадения. Используйте это, чтобы найти известный объект на сцене или совместить перекрывающиеся фотографии.
import cv2
import numpy as np
img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)
bf = cv2.BFMatcher(cv2.NORM_L2)
matches = bf.knnMatch(des1, des2, k=2)
good = [m for m, n in matches if m.distance < 0.75 * n.distance]
# build point correspondences
src = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
dst = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)
# RANSAC homography
H, mask = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
inliers = mask.ravel().tolist()
print(f"{sum(inliers)} inliers / {len(good)} matches")Локализация объекта
Это классический конвейер локализации объекта: найдите признаки на обоих изображениях, сопоставьте их, подгоните гомографию через RANSAC, затем спроецируйте ограничивающий прямоугольник объекта на сцену. Работает для плоских объектов или далёких 3D-объектов (где доминирует перспектива). Ломается на бестекстурных, симметричных или сильно перекрытых объектах — для них используйте детекторы на глубоком обучении.
import cv2
import numpy as np
img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)
bf = cv2.BFMatcher(cv2.NORM_L2)
good = [m for m, n in bf.knnMatch(des1, des2, k=2)
if m.distance < 0.75 * n.distance]
src = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
dst = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)
H, _ = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
# project the object's corners into the scene
h, w = img1.shape
corners = np.float32([[0, 0], [w-1, 0], [w-1, h-1], [0, h-1]]).reshape(-1, 1, 2)
scene_corners = cv2.perspectiveTransform(corners, H)
out = cv2.cvtColor(img2, cv2.COLOR_GRAY2BGR)
cv2.polylines(out, [np.int32(scene_corners)], True, (0, 255, 0), 3)Детекция лиц
Каскадный классификатор Хаара
Каскады Хаара — классический детектор Виолы-Джонса: быстры на CPU и хороши для фронтальных лиц, но менее точны, чем современные детекторы на глубоком обучении (MTCNN, SSD, RetinaFace). scaleFactor (>1) управляет многомасштабным поиском: 1.1 = шаг 10%; меньше — медленнее, но тщательнее. minNeighbors фильтрует перекрывающиеся детекции; увеличивайте его, чтобы уменьшить ложные срабатывания.
import cv2
# load a pretrained cascade (shipped with OpenCV)
cascade_path = cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
face_cascade = cv2.CascadeClassifier(cascade_path)
print(face_cascade.empty()) # False = loaded ok
img = cv2.imread("people.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# detectMultiScale(gray, scaleFactor, minNeighbors, minSize, maxSize)
faces = face_cascade.detectMultiScale(
gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))
for (x, y, w, h) in faces:
cv2.rectangle(img, (x, y), (x+w, y+h), (255, 0, 0), 2)Детекция лиц на изображении
Детекция глаз (или улыбки) внутри ROI лица — стандартный приём эффективности: поиск глаз по всему изображению даёт много ложных срабатываний, а внутри подтверждённого ROI лица они редки. cv2.data.haarcascades указывает на каталог встроенных XML-файлов; доступны другие каскады (глаз, улыбки, тела, номерных знаков). Обрежьте ROI ДО вызова каскада.
import cv2
face_cascade = cv2.CascadeClassifier(
cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
eye_cascade = cv2.CascadeClassifier(
cv2.data.haarcascades + "haarcascade_eye.xml")
img = cv2.imread("people.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
faces = face_cascade.detectMultiScale(gray, 1.3, 5)
for (fx, fy, fw, fh) in faces:
cv2.rectangle(img, (fx, fy), (fx+fw, fy+fh), (255, 0, 0), 2)
# search for eyes INSIDE the face region (faster, fewer false positives)
roi_gray = gray[fy:fy+fh, fx:fx+fw]
roi_color = img[fy:fy+fh, fx:fx+fw]
eyes = eye_cascade.detectMultiScale(roi_gray)
for (ex, ey, ew, eh) in eyes:
cv2.rectangle(roi_color, (ex, ey), (ex+ew, ey+eh), (0, 255, 0), 2)Детекция лиц на видео
Детекция лиц в реальном времени с вебкамеры возможна на CPU благодаря скорости каскадов Хаара. Приём размытия ROI (GaussianBlur только по области лица) — простая техника приватности и анонимизации. Чтобы отслеживать лица между кадрами (избежать мерцания), сопоставляйте детекции по IoU и сглаживайте фильтром Калмана: одни каскады не имеют временной непрерывности.
import cv2
face_cascade = cv2.CascadeClassifier(
cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
cap = cv2.VideoCapture(0)
while True:
ret, frame = cap.read()
if not ret:
break
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
faces = face_cascade.detectMultiScale(gray, 1.1, 5)
for (x, y, w, h) in faces:
cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2)
# blur the face for privacy
frame[y:y+h, x:x+w] = cv2.GaussianBlur(
frame[y:y+h, x:x+w], (25, 25), 30)
cv2.imshow("face", frame)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Профиль / боковое лицо
Каскады Хаара специфичны для позы: фронтальный каскад пропускает боковые лица, поэтому сочетайте его с профильным. Поскольку профильный каскад обучен на одной стороне, детектируйте другую сторону, отразив изображение по горизонтали и зеркально вернув координаты. Он всё равно пропускает виды в три четверти; современные детекторы (DNN, MTCNN) обрабатывают все позы одной моделью.
import cv2
profile_cascade = cv2.CascadeClassifier(
cv2.data.haarcascades + "haarcascade_profileface.xml")
img = cv2.imread("people.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# detect left-facing profiles
profiles = profile_cascade.detectMultiScale(gray, 1.1, 5)
for (x, y, w, h) in profiles:
cv2.rectangle(img, (x, y), (x+w, y+h), (0, 0, 255), 2)
# also detect right-facing by flipping the image
flipped = cv2.flip(gray, 1)
profiles_r = profile_cascade.detectMultiScale(flipped, 1.1, 5)
h, w = gray.shape
for (x, y, fw, fh) in profiles_r:
cv2.rectangle(img, (w - x - fw, y), (w - x, y + fh), (255, 0, 0), 2)Детекция лиц через DNN
Модуль dnn в OpenCV умеет запускать предобученные модели Caffe/TensorFlow/ONNX: детекторы лиц на основе SSD и ResNet гораздо точнее каскадов Хаара и обрабатывают все позы одной моделью. blobFromImage за один вызов выполняет вычитание среднего и масштабирование. Детекции нормализованы в [0,1] — умножьте на (w, h, w, h), чтобы получить пиксельные рамки. Модели: SSD (Caffe), YuNet (ONNX, через cv.FaceDetectorYN).
import cv2
import numpy as np
model = cv2.dnn.readNetFromCaffe(
"deploy.prototxt", "weights.caffemodel")
img = cv2.imread("people.jpg")
h, w = img.shape[:2]
# build a 300x300 blob (mean subtraction + scale)
blob = cv2.dnn.blobFromImage(img, 1.0, (300, 300), (104, 177, 123))
model.setInput(blob)
detections = model.forward() # shape (1, 1, N, 7)
for i in range(detections.shape[2]):
conf = detections[0, 0, i, 2]
if conf > 0.5:
box = detections[0, 0, i, 3:7] * np.array([w, h, w, h])
x1, y1, x2, y2 = box.astype(int)
cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
cv2.putText(img, f"{conf:.2f}", (x1, y1 - 5),
cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1)Детекция объектов
Дескриптор HOG
HOG (гистограмма ориентированных градиентов) описывает локальную форму через гистограммы направлений краёв; в сочетании с линейным SVM это классический детектор объектов. Предобученный детектор людей работает для пешеходов в полный рост в вертикальных позах. winStride и scale обменивают скорость на полноту. Современные глубокие детекторы (YOLO, SSD) гораздо точнее, но HOG работает на CPU без файла модели.
import cv2
img = cv2.imread("person.jpg", cv2.IMREAD_GRAYSCALE)
# create HOG descriptor with the default detector
hog = cv2.HOGDescriptor()
hog.setSVMDetector(cv2.HOGDescriptor_getDefaultPeopleDetector())
# detectMultiScale returns (rectangles, weights)
boxes, weights = hog.detectMultiScale(
img, winStride=(8, 8), padding=(4, 4), scale=1.05)
for (x, y, w, h) in boxes:
cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 2)Визуализация признаков HOG
Стандартное окно HOG — 64x128 пикселей (размер пешехода INRIA). Параметры: окно (64x128), блок (16x16), шаг блока (8x8), ячейка (8x8), корзины (9). Каждый дескриптор имеет размерность 3780. Чтобы классифицировать свои объекты, извлеките HOG-признаки для многих положительных и отрицательных примеров, обучите линейный SVM (scikit-learn), затем задайте детектор через setSVMDetector.
import cv2
img = cv2.imread("person.jpg", cv2.IMREAD_GRAYSCALE)
img = cv2.resize(img, (64, 128)) # standard HOG window
hog = cv2.HOGDescriptor((64, 128), (16, 16), (8, 8), (8, 8), 9)
descriptor = hog.compute(img)
print(descriptor.shape) # (3780, 1)
# 9 bins per cell, 7x15 cells, 4 cells per block -> 3780 features
# this is the input vector to a linear SVM classifierСопоставление шаблонов
Сопоставление шаблонов скользит шаблоном по изображению и вычисляет оценку сходства — работает только для точных (или почти точных) совпадений без поворота и изменения масштаба. TM_CCOEFF_NORMED — самый устойчивый метод; результаты в [-1, 1]. Для нескольких совпадений порогуйте карту отклика и применяйте подавление немаксимумов, чтобы избежать перекрывающихся детекций.
import cv2
import numpy as np
img = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
template = cv2.imread("template.png", cv2.IMREAD_GRAYSCALE)
h, w = template.shape
# matchTemplate returns a correlation map
res = cv2.matchTemplate(img, template, cv2.TM_CCOEFF_NORMED)
# find the best match
min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(res)
top_left = max_loc
bottom_right = (top_left[0] + w, top_left[1] + h)
out = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
cv2.rectangle(out, top_left, bottom_right, (0, 255, 0), 2)
# find all matches above a threshold
loc = np.where(res >= 0.8)
for pt in zip(*loc[::-1]):
cv2.rectangle(out, pt, (pt[0] + w, pt[1] + h), (0, 0, 255), 1)Многомасштабное сопоставление шаблонов
Многомасштабное сопоставление перебирает диапазон масштабов — медленно, но работает, когда размер шаблона на изображении неизвестен. Оно всё равно не справляется с поворотом: для этого нужно перебирать и углы (очень медленно) или использовать сопоставление признаков. Для продакшен-детекции объектов применяйте обученный детектор (YOLO, SSD), а не сопоставление шаблонов.
import cv2
import numpy as np
img = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
template = cv2.imread("template.png", cv2.IMREAD_GRAYSCALE)
best = (-1, None, None) # (score, location, scale)
for scale in np.linspace(0.5, 1.5, 20):
resized = cv2.resize(template, None, fx=scale, fy=scale)
rh, rw = resized.shape
if rh > img.shape[0] or rw > img.shape[1]:
continue
res = cv2.matchTemplate(img, resized, cv2.TM_CCOEFF_NORMED)
_, max_val, _, max_loc = cv2.minMaxLoc(res)
if max_val > best[0]:
best = (max_val, max_loc, scale)
score, (x, y), scale = best
h, w = template.shape
out = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
rw, rh = int(w * scale), int(h * scale)
cv2.rectangle(out, (x, y), (x + rw, y + rh), (0, 255, 0), 2)Детекция объектов через DNN (YOLO)
Модуль dnn в OpenCV умеет запускать экспортированные веса YOLO/SSD/Faster-RCNN — полезно, когда нельзя установить полный DL-фреймворк. Разбор вывода YOLO многословен: каждая детекция содержит центр, размер, objectness и оценки по классам. Всегда применяйте NMSBoxes (подавление немаксимумов), чтобы схлопнуть перекрывающиеся рамки в одну. Для реального времени используйте YOLOv4-tiny или переходите на ONNX с более быстрым бэкендом.
import cv2
import numpy as np
# load a YOLO model (weights + cfg)
net = cv2.dnn.readNet("yolov3.weights", "yolov3.cfg")
with open("coco.names") as f:
classes = [line.strip() for line in f.readlines()]
layer_names = net.getLayerNames()
out_layers = [layer_names[i - 1] for i in net.getUnconnectedOutLayers()]
img = cv2.imread("street.jpg")
blob = cv2.dnn.blobFromImage(img, 1/255.0, (416, 416), swapRB=True, crop=False)
net.setInput(blob)
outputs = net.forward(out_layers)
# parse YOLO output: each detection is [cx, cy, w, h, obj, class_scores...]
h, w = img.shape[:2]
boxes, confs, ids = [], [], []
for out in outputs:
for det in out:
scores = det[5:]
cls = int(np.argmax(scores))
conf = scores[cls]
if conf > 0.5:
cx, cy, bw, bh = (det[:4] * [w, h, w, h]).astype(int)
boxes.append([cx - bw//2, cy - bh//2, bw, bh])
confs.append(float(conf))
ids.append(cls)
idxs = cv2.dnn.NMSBoxes(boxes, confs, 0.5, 0.4) # non-max suppressionСегментация изображений
Кластеризация K-Means
K-means кластеризует пиксели по цвету — простой способ постеризовать или сегментировать изображение на K доминирующих цветов. Передавайте пиксели float32 формы (N, 3) (или (N, 5), если добавите координаты xy для пространственной кластеризации). Большее K даёт более тонкое разделение цветов. Для пространственной связности добавьте к каждому пикселю координаты (x, y); для чистой квантизации цвета используйте только BGR.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# reshape to a list of pixels (N, 3) in float32
pixels = img.reshape(-1, 3).astype(np.float32)
# kmeans(data, K, criteria, attempts, flags)
K = 4
criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)
_, labels, centers = cv2.kmeans(pixels, K, None, criteria, 10,
cv2.KMEANS_RANDOM_CENTERS)
# rebuild the image with cluster centers
centers = np.uint8(centers)
seg = centers[labels.flatten()].reshape((h, w, 3))GrabCut
GrabCut — интерактивное извлечение переднего плана: вы задаёте ограничивающий прямоугольник, и он итеративно моделирует передний и з адний план гауссовыми смесями. Для более точного результата уточните через GC_INIT_WITH_MASK, вручную разметив пиксели (точно передний план / точно фон). Хорошо работает для одного заметного объекта на относительно простом фоне.
import cv2
import numpy as np
img = cv2.imread("person.jpg")
h, w = img.shape[:2]
# initialize mask (all probable background)
mask = np.zeros((h, w), np.uint8)
# define a rectangle around the foreground object
rect = (50, 50, w - 100, h - 100)
# internal scratch arrays
bgd = np.zeros((1, 65), np.float64)
fgd = np.zeros((1, 65), np.float64)
# run GrabCut: 5 iterations
cv2.grabCut(img, mask, rect, bgd, fgd, 5, cv2.GC_INIT_WITH_RECT)
# mask values: 0=bg, 1=fg, 2=probable bg, 3=probable fg
fg_mask = np.where((mask == 1) | (mask == 3), 255, 0).astype(np.uint8)
result = cv2.bitwise_and(img, img, mask=fg_mask)Водораздел (watershed)
Watershed трактует изображение как топографическую карту (интенсивность = высота) и «заливает» бассейны от маркеров-семян: без хороших семян даёт сильную пере-сегментацию. Приём с преобразованием расстояния генерирует надёжные семена переднего плана для касающихся объектов (например, перекрывающихся монет). Маркеры: 0=неизвестно, 1=фон, 2..N=объекты, -1=граница. Это классический конвейер «разделения касающихся объектов».
import cv2
import numpy as np
img = cv2.imread("coins.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# threshold to separate coins from background
_, binary = cv2.threshold(gray, 0, 255,
cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
# noise removal
kernel = np.ones((3, 3), np.uint8)
opening = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel, iterations=2)
# sure background area
sure_bg = cv2.dilate(opening, kernel, iterations=3)
# sure foreground: distance transform + threshold
dist = cv2.distanceTransform(opening, cv2.DIST_L2, 5)
_, sure_fg = cv2.threshold(dist, 0.5 * dist.max(), 255, 0)
sure_fg = np.uint8(sure_fg)
# unknown region (between sure fg and sure bg)
unknown = cv2.subtract(sure_bg, sure_fg)
# marker labelling
_, markers = cv2.connectedComponents(sure_fg)
markers = markers + 1
markers[unknown == 255] = 0
# watershed modifies markers in place
markers = cv2.watershed(img, markers)
img[markers == -1] = [255, 0, 0] # boundaries in redЗаливка (flood fill)
floodFill — инструмент «волшебная палочка»: начните с пикселя-семени и залейте все связанные пиксели, цвет которых отличается от семени (FIXED_RANGE) или от предыдущего пикселя в пределах loDiff/upDiff. Маска должна быть на 2 пикселя больше изображения (рамка в 1 пиксель с каждой стороны). Полезно для выращивания областей, простой замены фона и интерактивного выделения.
import cv2
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
mask = np.zeros((h + 2, w + 2), np.uint8)
# floodFill fills a connected region similar to the seed pixel
# (image, mask, seedPoint, newVal, loDiff, upDiff, flags)
cv2.floodFill(img, mask, (100, 100), (0, 255, 0),
loDiff=(20, 20, 20), upDiff=(20, 20, 20),
flags=8 | cv2.FLOODFILL_FIXED_RANGE)
# FLOODFILL_FIXED_RANGE: compare to the seed pixel (strict)
# 4-connectivity (4) or 8-connectivity (8)
# extract the filled mask
filled_mask = mask[1:-1, 1:-1] # the mask is padded by 1Связные компоненты
connectedComponents помечает каждую белую область уникальным целым — быстрее findContours, когда нужны только количество, площадь и центроиды. connectedComponentsWithStats дополнительно возвращает ограничивающие рамки и площади. Метка 0 всегда фон. Связность по умолчанию 8 (диагонали включены); передайте connectivity=4 для более строгой. Используйте для подсчёта частиц и анализа пятен.
import cv2
import numpy as np
img = cv2.imread("blobs.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
# connectedComponents returns (num_labels, labels)
num, labels = cv2.connectedComponents(binary)
print(f"found {num - 1} objects (label 0 is background)")
# connectedComponentsWithStats also gives area and bounding box
num, labels, stats, centroids = cv2.connectedComponentsWithStats(binary)
for i in range(1, num):
x, y, w, h, area = stats[i]
cx, cy = centroids[i]
cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 1)
cv2.putText(img, str(area), (x, y - 5),
cv2.FONT_HERSHEY_SIMPLEX, 0.4, (0, 0, 255), 1)Mean-Shift / PyrMeanShiftFiltering
pyrMeanShiftFiltering — непараметрическая сегментация, которая «выравнивает» области похожего цвета, сохраняя края; часто используется как шаг предобработки перед сегментацией по контурам. sp (пространственный радиус) управляет тем, как далеко алгоритм смотрит в пространстве; sr (цветовой радиус) — допуском по цвету. Большие значения дают более крупные и гладкие области.
import cv2
img = cv2.imread("photo.jpg")
# pyrMeanShiftFiltering: edge-preserving smoothing that homogenizes regions
# (spatialRadius, colorRadius) — larger values merge more
filtered = cv2.pyrMeanShiftFiltering(img, sp=20, sr=40)
# now segment on the filtered image
gray = cv2.cvtColor(filtered, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 0, 255,
cv2.THRESH_BINARY + cv2.THRESH_OTSU)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
cv2.CHAIN_APPROX_SIMPLE)
out = img.copy()
cv2.drawContours(out, contours, -1, (0, 255, 0), 2)Калибровка камеры
Калибровка по шахматной доске
Калибровка камеры находит внутреннюю матрицу (фокусное расстояние, главная точка) и коэффициенты искажений объектива по изображениям известного шаблона (шахматная доска стандартна, потому что углы легко детектируются). Нужно ~10–20 изображений с разных углов. cornerSubPix уточняет углы до субпиксельной точности — необходимо для хорошей калибровки. Размер шаблона для findChessboardCorners — внутренние углы (квадраты-1).
import cv2
import numpy as np
import glob
# prepare object points (0,0,0), (1,0,0), ..., for a 7x6 board
objp = np.zeros((6 * 7, 3), np.float32)
objp[:, :2] = np.mgrid[0:7, 0:6].T.reshape(-1, 2)
objpoints = [] # 3-D real-world points
imgpoints = [] # 2-D image points
for fname in glob.glob("calib/*.jpg"):
img = cv2.imread(fname)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# findChessboardCorners returns corners (or None)
ret, corners = cv2.findChessboardCorners(gray, (7, 6), None)
if ret:
# refine to sub-pixel accuracy
corners2 = cv2.cornerSubPix(gray, corners, (11, 11), (-1, -1),
(cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001))
objpoints.append(objp)
imgpoints.append(corners2)
# calibrate
ret, mtx, dist, rvecs, tvecs = cv2.calibrateCamera(
objpoints, imgpoints, gray.shape[::-1], None, None)
print("camera matrix:\n", mtx)Устранение искажений
undistort убирает радиальные и тангенциальные искажения объектива по параметрам калибровки. Для видео один раз вычислите карты через initUndistortRectifyMap и применяйте remap на каждом кадре — гораздо быстрее повторных вызовов undistort. getOptimalNewCameraMatrix с alpha=1 сохраняет все пиксели (с чёрными рамками); alpha=0 обрезает до допустимой области.
import cv2
import numpy as np
# mtx, dist come from calibrateCamera
img = cv2.imread("distorted.jpg")
h, w = img.shape[:2]
# method 1: simple undistort
undistorted = cv2.undistort(img, mtx, dist)
# method 2: pre-compute the maps for speed (run once, reuse many times)
newcameramtx, roi = cv2.getOptimalNewCameraMatrix(
mtx, dist, (w, h), 1, (w, h))
mapx, mapy = cv2.initUndistortRectifyMap(
mtx, dist, None, newcameramtx, (w, h), cv2.CV_16SC2)
undistorted2 = cv2.remap(img, mapx, mapy, cv2.INTER_LINEAR)
# crop to the valid ROI
x, y, rw, rh = roi
undistorted2 = undistorted2[y:y+rh, x:x+rw]Оценка позы (ArUco)
Маркеры ArUco — квадратные опорные маркеры (как QR-коды) для оценки позы: зная физический размер маркера и калибровку камеры, вы получаете его 3D-поворот (rvec) и смещение (tvec) относительно камеры. Доступны в opencv-contrib. drawFrameAxes рисует локальные оси X/Y/Z маркера: красный=X, зелёный=Y, синий=Z, длина в метрах.
import cv2
# load a predefined ArUco dictionary
aruco_dict = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
params = cv2.aruco.DetectorParameters()
detector = cv2.aruco.ArucoDetector(aruco_dict, params)
img = cv2.imread("marker.png")
corners, ids, rejected = detector.detectMarkers(img)
if ids is not None:
cv2.aruco.drawDetectedMarkers(img, corners, ids)
# estimate pose (marker size in meters, camera matrix, distortion)
rvecs, tvecs, _ = cv2.aruco.estimatePoseSingleMarkers(
corners, 0.05, mtx, dist)
for rvec, tvec in zip(rvecs, tvecs):
cv2.drawFrameAxes(img, mtx, dist, rvec, tvec, 0.05)Поза по опорным точкам (SolvePnP)
solvePnP (Perspective-n-Point) восстанавливает позу камеры по N соответствиям 3D-2D — нужно минимум 4 точки. Используйте SOLVEPNP_ITERATIVE (по умолчанию) для точности или SOLVEPNP_IPPE для плоских целей. rvec — вектор поворота (ось × угол); Rodrigues преобразует его в матрицу 3x3. Это основа маркерного AR и 6-DOF трекинга.
import cv2
import numpy as np
# 3-D coordinates of known object points (e.g. a cube corner)
obj_points = np.array([
[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
[0, 0, -1], [1, 0, -1], [1, 1, -1], [0, 1, -1],
], dtype=np.float32)
# corresponding 2-D image points (detected via feature matching etc.)
img_points = np.array([
[120, 90], [220, 88], [225, 190], [115, 195],
[80, 60], [240, 55], [248, 210], [70, 215],
], dtype=np.float32)
# solvePnP(objectPoints, imagePoints, cameraMatrix, distCoeffs)
ret, rvec, tvec = cv2.solvePnP(obj_points, img_points, mtx, dist)
print("rotation:", rvec.ravel())
print("translation:", tvec.ravel())
# project the 3-D points back to verify
proj, _ = cv2.projectPoints(obj_points, rvec, tvec, mtx, dist)Ошибка репроекции
Ошибка репроекции — золотой стандарт качества калибровки: она измеряет, насколько далеко проецируемые 3D-точки ложатся от найденных 2D-точек. Хорошая калибровка — ниже 0.5 px в среднем; выше 1 px обычно указывает на плохой набор изображений, неверный размер шаблона или смаз. Ошибка по каждому изображению помогает найти и отбросить неудачные кадры калибровки.
import cv2
import numpy as np
# after calibrateCamera or solvePnP, check accuracy
mean_err = 0
total = 0
for i in range(len(objpoints)):
# project the 3-D points using the estimated pose
proj, _ = cv2.projectPoints(objpoints[i], rvecs[i], tvecs[i], mtx, dist)
err = cv2.norm(imgpoints[i], proj, cv2.NORM_L2) / len(proj)
mean_err += err
total += 1
print(f"mean reprojection error: {mean_err / total:.3f} px")
# good calibrations are typically < 0.5 px per cornerГлубина и стерео
Карта диспаратности
StereoBM вычисляет карту диспаратности (пиксельное смещение между левым и правым) для откалиброванной стереопары: близкие объекты имеют большую диспаратность. numDisparities должен быть кратен 16; blockSize — нечётным. Выход — int16, масштабированный на 16 (делите на 16.0 для диспаратности в пикселях). StereoSGBM (полуглобальное блочное сопоставление) медленнее, но гораздо точнее.
import cv2
# stereo pair (rectified: corresponding points on the same row)
imgL = cv2.imread("left.png", cv2.IMREAD_GRAYSCALE)
imgR = cv2.imread("right.png", cv2.IMREAD_GRAYSCALE)
# StereoBM (block matching, fast)
stereo = cv2.StereoBM_create(numDisparities=16, blockSize=15)
disparity = stereo.compute(imgL, imgR)
# normalize for display
disp_vis = cv2.normalize(disparity, None, 0, 255,
cv2.NORM_MINMAX, cv2.CV_8U)StereoSGBM
StereoSGBM обеспечивает гладкость вдоль строк (полуглобальное сопоставление) — гораздо точнее StereoBM ценой ~5x времени работы. P1/P2 штрафуют изменения диспаратности на 1 и больше 1 соответственно; эмпирическое правило: P1=8*C*blockSize² и P2=32*C*blockSize², где C — число каналов. Параметры speckle* фильтруют мелкие шумные области диспаратности.
import cv2
imgL = cv2.imread("left.png", cv2.IMREAD_GRAYSCALE)
imgR = cv2.imread("right.png", cv2.IMREAD_GRAYSCALE)
sgbm = cv2.StereoSGBM_create(
minDisparity=0,
numDisparities=128,
blockSize=5,
P1=8 * 3 * 5 * 5,
P2=32 * 3 * 5 * 5,
disp12MaxDiff=1,
uniquenessRatio=10,
speckleWindowSize=100,
speckleRange=32,
)
disparity = sgbm.compute(imgL, imgR)
disp_vis = cv2.normalize(disparity, None, 0, 255,
cv2.NORM_MINMAX, cv2.CV_8U)Стереокалибровка и ректификация
Стереосопоставление требует ректификации изображений: эпиполярные линии выравниваются горизонтально, чтобы соответствующие точки лежали в одной строке. Конвейер: откалибровать каждую камеру, выполнить стереокалибровку для поиска R и T между ними, stereoRectify для вычисления преобразований ректификации, затем один раз remap каждого кадра. После ректификации вычисление диспаратности — одномерный поиск вдоль строк.
import cv2
import numpy as np
# calibrate each camera separately, then stereo-calibrate
ret, mtxL, distL, rvecsL, tvecsL = cv2.calibrateCamera(
objpoints, imgpointsL, grayL.shape[::-1], None, None)
ret, mtxR, distR, rvecsR, tvecsR = cv2.calibrateCamera(
objpoints, imgpointsR, grayR.shape[::-1], None, None)
# stereo calibration: finds the rigid transform between cameras
flags = cv2.CALIB_FIX_INTRINSIC
ret, mtxL, distL, mtxR, distR, R, T, E, F = cv2.stereoCalibrate(
objpoints, imgpointsL, imgpointsR, mtxL, distL, mtxR, distR,
grayL.shape[::-1], flags=flags)
# stereo rectification: aligns epipolar lines to be horizontal
R1, R2, P1, P2, Q, _, _ = cv2.stereoRectify(
mtxL, distL, mtxR, distR, grayL.shape[::-1], R, T)
# pre-compute the rectification maps
mapL1, mapL2 = cv2.initUndistortRectifyMap(
mtxL, distL, R1, P1, grayL.shape[::-1], cv2.CV_16SC2)
mapR1, mapR2 = cv2.initUndistortRectifyMap(
mtxR, distR, R2, P2, grayR.shape[::-1], cv2.CV_16SC2)
rectL = cv2.remap(imgL, mapL1, mapL2, cv2.INTER_LINEAR)
rectR = cv2.remap(imgR, mapR1, mapR2, cv2.INTER_LINEAR)Глубина из диспаратности
Глубина обратно пропорциональна диспаратности: depth = focal × baseline / disparity. База (расстояние между камерами) и фокусное расстояние должны быть в согласованных единицах (обычно фокус в пикселях, база в метрах даёт глубину в метрах). Диспаратность шумна для далёких объектов (малая диспаратность — большая ошибка глубины), поэтому стереокамерам нужна широкая база для дальнего диапазона.
import cv2
import numpy as np
# given a disparity map and the stereo baseline + focal length:
# depth = (focal_length * baseline) / disparity
focal = 700.0 # pixels (from camera matrix)
baseline = 0.1 # meters (distance between cameras)
disparity = sgbm.compute(rectL, rectR).astype(np.float32) / 16.0
# avoid division by zero
disparity[disparity <= 0] = 0.1
depth = (focal * baseline) / disparity # in meters
# cap to a sensible range
depth = np.clip(depth, 0.1, 100.0)
depth_vis = cv2.normalize(depth, None, 0, 255, cv2.NORM_MINMAX, cv2.CV_8U)Оптический поток (Лукас-Канаде)
Лукас-Канаде вычисляет разреженный оптический поток: он отслеживает набор ключевых точек между кадрами, предполагая малое локальное движение. Быстр и точен при умеренном движении; ломается при большом или быстром движении (используйте пирамиду — calcOpticalFlowPyrLK уже это делает). status==1 означает, что точ ка успешно отслежена. Для плотного потока по пикселям используйте calcOpticalFlowFarneback — гораздо медленнее, но даёт полное поле движения.
import cv2
import numpy as np
cap = cv2.VideoCapture("traffic.mp4")
ret, prev = cap.read()
prev_gray = cv2.cvtColor(prev, cv2.COLOR_BGR2GRAY)
# detect good features to track
prev_pts = cv2.goodFeaturesToTrack(prev_gray, 100, 0.3, 7)
while True:
ret, frame = cap.read()
if not ret:
break
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
# sparse optical flow (Lucas-Kanade)
next_pts, status, err = cv2.calcOpticalFlowPyrLK(
prev_gray, gray, prev_pts, None)
good_new = next_pts[status == 1]
good_old = prev_pts[status == 1]
for new, old in zip(good_new, good_old):
a, b = new.ravel()
c, d = old.ravel()
cv2.line(frame, (int(a), int(b)), (int(c), int(d)), (0, 255, 0), 2)
cv2.circle(frame, (int(a), int(b)), 3, (0, 0, 255), -1)
cv2.imshow("flow", frame)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
prev_gray = gray.copy()
prev_pts = good_new.reshape(-1, 1, 2)
cap.release()Утилиты и советы
Измерение производительности
TickMeter — самый чистый способ бенчмарка вызовов OpenCV: getTimeMilli возвращает миллисекунды по настенным часам. getTickCount/getTickFrequency дают точный по тактам тайминг. Всегда усредняйте по многим итерациям, чтобы амортизировать дрожание, и отключайте cv2.imshow при бенчмарке (рендеринг GUI доминирует). setNumThreads управляет нижележащим параллельным бэкендом (TBB/OpenMP).
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# TickMeter: high-precision timer
tm = cv2.TickMeter()
tm.start()
for _ in range(100):
blurred = cv2.GaussianBlur(img, (5, 5), 0)
tm.stop()
print(f"avg: {tm.getTimeMilli() / 100:.3f} ms")
# getTickCount / getTickFrequency
t0 = cv2.getTickCount()
edges = cv2.Canny(img, 50, 150)
t1 = cv2.getTickCount()
print(f"Canny: {(t1 - t0) / cv2.getTickFrequency() * 1000:.2f} ms")
# set USE_AVX / thread count
cv2.setNumThreads(4)
print(cv2.getNumThreads())События мыши
setMouseCallback регистрирует обработчик событий мыши для именованного окна — полезно для интерактивного выбора ROI, инструментов аннотации и простых приложений для рисования. Частые события: LBUTTONDOWN, LBUTTONUP, MOUSEMOVE, RBUTTONDOWN. Обработчик должен быть функцией верхнего уровня (или глобальной); глобальные переменные — стандартный способ разделять состояние, так как сигнатура callback фиксирована.
import cv2
import numpy as np
drawing = False
ix, iy = -1, -1
def on_mouse(event, x, y, flags, param):
global drawing, ix, iy
if event == cv2.EVENT_LBUTTONDOWN:
drawing = True
ix, iy = x, y
elif event == cv2.EVENT_MOUSEMOVE and drawing:
cv2.rectangle(img, (ix, iy), (x, y), (0, 255, 0), -1)
elif event == cv2.EVENT_LBUTTONUP:
drawing = False
cv2.rectangle(img, (ix, iy), (x, y), (0, 255, 0), -1)
img = np.zeros((512, 512, 3), np.uint8)
cv2.namedWindow("canvas")
cv2.setMouseCallback("canvas", on_mouse)
while True:
cv2.imshow("canvas", img)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cv2.destroyAllWindows()Трекбар
Трекбары позволяют настраивать параметры интерактивно без перезапуска скрипта — бесценно для поиска хороших порогов, размеров ядер и диапазонов HSV. Callback вызывается при каждом изменении (пустая функция подойдёт, если вы опрашиваете getTrackbarPos в основном цикле). Трекбары нужно создавать на именованном окне и читать через getTrackbarPos(window, name).
import cv2
import numpy as np
def nothing(x):
pass
img = np.zeros((300, 512, 3), np.uint8)
cv2.namedWindow("image")
# create trackbars
cv2.createTrackbar("R", "image", 0, 255, nothing)
cv2.createTrackbar("G", "image", 0, 255, nothing)
cv2.createTrackbar("B", "image", 0, 255, nothing)
cv2.createTrackbar("switch", "image", 0, 1, nothing)
while True:
cv2.imshow("image", img)
if cv2.waitKey(1) & 0xFF == 27: # Esc to quit
break
r = cv2.getTrackbarPos("R", "image")
g = cv2.getTrackbarPos("G", "image")
b = cv2.getTrackbarPos("B", "image")
s = cv2.getTrackbarPos("switch", "image")
if s == 0:
img[:] = 0
else:
img[:] = [b, g, r]
cv2.destroyAllWindows()Выбор ROI
selectROI открывает интерактивное окно, где пользователь тянет прямоугольник и нажимает Enter/Space, — гораздо проще, чем писать свой обработчик мыши. Нажмите 'c' для отмены (вернёт нули). selectROIs позволяет выбрать несколько прямоугольников подряд. Возвращаемый кортеж — (x, y, w, h); обрезайте через img[y:y+h, x:x+w].
import cv2
img = cv2.imread("photo.jpg")
# built-in ROI selector (drag a rectangle)
roi = cv2.selectROI("select", img, showCrosshair=True, fromCenter=False)
cv2.destroyAllWindows()
x, y, w, h = roi
cropped = img[y:y+h, x:x+w]
# multiple ROIs
rois = cv2.selectROIs("select", img, showCrosshair=True, fromCenter=False)
for r in rois:
x, y, w, h = r
cv2.imshow("roi", img[y:y+h, x:x+w])
cv2.waitKey(0)
cv2.destroyAllWindows()Частые ловушки
Эти пять ловушек вызывают большинство багов OpenCV: путаница BGR/RGB (красный и синий меняются местами), переполнение uint8 (тёмные и светлые артефакты), порядок координат (ROI со смещением на единицу), None вместо отсутствующего файла (последующие операции падают с загадочными ошибками) и забытый waitKey (окна не обновляются). Запомните их пораньше — каждый разработчик OpenCV попадает в каждую хотя бы раз.
import cv2
import numpy as np
# 1. BGR vs RGB — imshow expects BGR; matplotlib expects RGB
img = cv2.imread("p.jpg")
# plt.imshow(cv2.cvtColor(img, cv2.COLOR_BGR2RGB)) # correct
# plt.imshow(img) # colors look wrong
# 2. uint8 overflow — use cv2 ops or upcast
a = np.array([200], np.uint8)
print(a + 100) # [44] (wraps, WRONG)
print(cv2.add(a, 100)) # [[255]] (saturates, RIGHT)
# 3. (x, y) vs (row, col) — drawing uses (x,y), NumPy uses [y,x]
cv2.rectangle(img, (10, 20), (110, 120), (0, 255, 0), 2) # x=10..110
roi = img[20:120, 10:110] # rows 20..120, cols 10..110 (same region)
# 4. None returned by imread when the file is missing
img = cv2.imread("missing.jpg")
if img is None:
raise FileNotFoundError("could not read image")
# 5. waitKey is mandatory for imshow to actually render
cv2.imshow("img", img)
cv2.waitKey(1) # without this, the window may stay blankСвязанные сниппеты OpenCV
Copy-paste ready code for common tasks.
Read and Write Images
Load, display, and save images in various formats.
Resize and Crop
Resize with interpolation and crop regions of interest.
Color Conversion
Convert between BGR, RGB, HSV, and grayscale.
Blur and Filter
Smooth and sharpen images with kernels.
Edge Detection
Detect edges with Canny, Sobel, and Laplacian.
Contours
Find, draw, and measure contours.
Face Detection
Detect faces with a Haar cascade classifier.
Threshold
Apply binary, adaptive, and Otsu thresholding.
Was this helpful?