Skip to content

OpenCV Шпаргалка

Открытая библиотека компьютерного зрения и машинного обучения.

01

С чего начать

Чтение, показ и сохранение изображений

OpenCV читает изображения в порядке BGR (а не RGB) — частая ловушка при взаимодействии с matplotlib или PIL. cv2.waitKey(0) блокируется до нажатия клавиши; всегда вызывайте destroyAllWindows(), чтобы закрыть окна. Качество JPEG — от 0 до 100.

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

opencv
# 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).

opencv
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] — самый быстрый способ работы с отдельным цветовым каналом.

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

opencv
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
02

Захват видео

Открытие вебкамеры

VideoCapture(0) открывает вебкамеру по умолчанию; используйте 1, 2... для дополнительных камер. Всегда вызывайте cap.release(), чтобы освободить устройство: если забыть, камера может остаться занятой для других приложений. waitKey(1) ждёт ~1 мс; трюк с & 0xFF обеспечивает совместимость на 64-битных системах, где waitKey возвращает больше 8 бит.

opencv
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).

opencv
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(), чтобы сбросить буфер и закрыть файл.

opencv
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), прежде чем ручная экспозиция начнёт действовать.

opencv
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 на каждый кадр; для бенчмарка отключайте отображение. Для детерминированного тайминга накапливайте кадры в потоке и обрабатывайте из очереди.

opencv
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()
03

Рисование

Линия и прямоугольник

Все функции рисования изменяют изображение на месте — передавайте копию, если нужен оригинал. Координаты — (x, y), противоположно индексации NumPy [y, x]. Цвета — кортежи BGR. Используйте thickness=-1 для залитых фигур и cv2.LINE_AA для сглаженных (антиалиасинговых) линий на диагональных краях.

opencv
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° — вправо, против часовой стрелки). Рисование частичных дуг — стандартный способ отображать сектора круговых диаграмм или индикаторы направления движения.

opencv
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 соединяет последнюю точку с первой.

opencv
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 возвращает ((ширина, высота), базовую линию) — полезно для центрирования текста или фона под ним.

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

opencv
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 нет нативной альфы для фигур. Всегда рисуйте сплошной текст ПОСЛЕ смешивания, чтобы он оставался чётким; текст на оверлее до смешивания становится размытым. Этот паттерн повсюду в визуализации детекции и сегментации.

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)
04

Арифметика изображений

Сложение и вычитание

cv2.add в OpenCV насыщается на 255 (250 + 10 = 255), а + в NumPy заворачивается (250 + 10 = 8 из-за переполнения uint8). Для изображений всегда используйте cv2.add / cv2.subtract: заворачивание создаёт видимые чёрные и белые артефакты. absdiff — рабочая лошадка вычитания фона и обнаружения движения.

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

opencv
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 и замены фона.

opencv
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) или оптический поток. Морфологическое открытие убирает шум, дилатация сливает близкие пятна.

opencv
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, которые планируете переиспользовать: срез возвращает представление, разделяющее оригинал.

opencv
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 в одном конвейере — главная причина загадочных тёмных и светлых артефактов на пикселях.

opencv
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
05

Геометрические преобразования

Масштабирование

INTER_AREA лучше для уменьшения (избегает алиасинга), INTER_CUBIC или INTER_LINEAR — для увеличения. INTER_NEAREST самый быстрый, но блочный — используется для изображений меток и масок, где нельзя вводить новые значения пикселей. Кортеж dsize — (ширина, высота), противоположно img.shape, где (высота, ширина).

opencv
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) и сдвиньте матрицу поворота, иначе углы большого повёрнутого изображения срежутся.

opencv
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, чтобы управлять заполнением областей за границами.

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

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

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

opencv
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)
06

Фильтрация изображений

Среднее размытие (box filter)

Среднее размытие — простейший низкочастотный фильтр: он заменяет каждый пиксель средним по окрестности. Ядра должны быть нечётными и положительными. Большие ядра размывают сильнее, но и быстрее уничтожают детали. Используйте его, когда нужны именно равномерные веса; для естественных изображений гауссово размытие почти всегда лучше.

opencv
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, даунсэмплингом и лапласианом, чтобы подавить усиление шума.

opencv
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-фильтра из-за сортировки.

opencv
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 смешивают больше цветов.

opencv
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 (вычитание размытой копии) более управляема и именно её используют большинство фоторедакторов.

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

opencv
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)
07

Морфологические операции

Эрозия и дилатация

Эрозия сжимает области переднего плана (белые) и удаляет мелкие пятна шума; дилатация расширяет их и заполняет мелкие дыры. Форма ядра важна: RECT для общего применения, ELLIPSE для более круглых объектов, CROSS для утоньшения и соединения вдоль осей. iterations=N повторяет операцию N раз, что эквивалентно большему ядру.

opencv
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))

Открытие и закрытие

Открытие (эрозия→дилатация) удаляет мелкие яркие пятна, не меняя размер крупных объектов. Закрытие (дилатация→эрозия) заполняет мелкие тёмные дыры. Они идемпотентны: двукратное применение равно однократному. Классический паттерн шумоподавления — закрытие, затем открытие (или наоборот), чтобы справиться с обоими типами дефектов.

opencv
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 он даёт залитые широкие края, поэтому хорош для выделения областей, а не для измерения точного положения краёв.

opencv
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 — мелкие тёмные структуры. Вместе их используют для извлечения теней и бликов и как быстрый корректор неравномерного освещения (приём деления на фон распространён в сканерах документов).

opencv
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 быстрее и дают чище результат.

opencv
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:
        break

Hit-or-Miss

Hit-or-miss — морфологический сопоставитель шаблонов: он находит точные конфигурации пикселей переднего и заднего плана, полезен для обнаружения конкретных форм вроде углов или T-образных соединений. Ядро использует 1 для требуемого переднего плана, -1 для требуемого фона, 0 для «не важно». Метод нишевый, но незаменим для точного поиска шаблонов.

opencv
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")
08

Обнаружение краёв

Детектор краёв Canny

Canny — самый используемый детектор краёв: гауссово сглаживание → градиенты Собеля → подавление немаксимумов → гистерезис (два порога). Пиксели выше высокого порога — края; между низким и высоким — края, только если связаны с сильным краем. Приём авто-порога (медиана × 0.7/1.3) хорошо работает для разнообразных изображений.

opencv
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 и многих детекторов признаков.

opencv
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, потому что вторая производная сильно уходит в минус.

opencv
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, ориентация краёв).

opencv
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 и размера ядра шумоподавления — здесь уходит большая часть инженерных усилий.

opencv
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)
09

Контуры

Поиск контуров

findContours изменяет исходное изображение в OpenCV 3.x — передавайте копию, если бинарное изображение нужно после. RETR_EXTERNAL возвращает только внешние контуры (быстрее всего); RETR_TREE даёт полную иерархию для вложенных фигур (дыры внутри объектов). CHAIN_APPROX_SIMPLE отбрасывает избыточные точки на прямых линиях, экономя память.

opencv
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 заливает контур. Рисование на пустом изображении — стандартный способ построить маску контура для последующих операций вроде среднего цвета или гистограммы по маске.

opencv
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 — простейшие дескрипторы формы для классификации.

opencv
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 — наименьшая окружность, содержащая контур.

opencv
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, круг=много.

opencv
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)

Выпуклая оболочка и дефекты

Выпуклая оболочка — наименьшая выпуклая фигура, содержащая контур: полезна для измерения компактности объекта и обнаружения рук и пальцев через дефекты выпуклости. Глубина каждого дефекта показывает, насколько контур «вдаётся» внутрь относительно оболочки; глубокие дефекты на силуэте руки обычно соответствуют промежуткам между пальцами.

opencv
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)
10

Пороговая бинаризация

Базовый порог

THRESH_BINARY: выше->255, ниже->0. THRESH_TRUNC: выше->ограничено порогом, ниже->без изменений. THRESH_TOZERO: выше->без изменений, ниже->0. Возвращаемый ret для обычной бинаризации равен входному порогу, но становится осмысленным для Otsu/Triangle. Выбирайте тип по тому, как нужно обрабатывать пиксели вне диапазона.

opencv
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 вычитает константу из локального среднего; увеличивайте её, чтобы подавить низкоконтрастный шум.

opencv
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 — вычисленный порог.

opencv
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, чтобы уменьшить пятна шума в маске.

opencv
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 для равномерного освещения, адаптивный — для неравномерного. Морфологическое «закрытие, затем открытие» убирает и внутренние дыры, и внешние пятна. Всегда проверяйте бинарную маску: параметры порога почти всегда зависят от изображения и требуют подстройки под набор данных.

opencv
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) предпочитают чёрный текст на белом фоне — инвертируйте, если ваша бинаризация даёт обратное.

opencv
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)
11

Цветовые пространства

BGR / RGB / Gray

OpenCV по умолчанию читает изображения как BGR; большинство других библиотек (matplotlib, PIL, scikit-image) используют RGB. Забыть cvtColor — самая частая причина изображений с «перепутанными красным и синим». Преобразование в оттенки серого использует перцептивные веса (Y = 0.299R + 0.587G + 0.114B), а не простое среднее.

opencv
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 — основное пространство для цветовой сегментации, потому что тон примерно инвариантен к изменению яркости; используйте его для отслеживания объектов по цвету.

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

opencv
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 (обратная проекция гистограммы тона) или фильтром Калмана для сглаживания движения.

opencv
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 в правильном порядке для целевого цветового пространства. Приём «обнулить два канала» — классический способ визуализировать вклад одного цветового канала.

opencv
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 лучше для некоторых эффектов затенения. Выбирайте пространство, в котором ваша операция инвариантна к тому, что вам не важно.

opencv
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)
12

Гистограммы

Вычисление гистограммы

calcHist принимает список изображений, список каналов, необязательную маску (None = всё изображение), число корзин и диапазон значений. Для многомерных гистограмм (например, 2-D тон-насыщенность) передайте два канала и два размера корзин — это используется в обратной проекции гистограммы для отслеживания цвета. Гистограмма каждого канала вычисляется независимо.

opencv
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 для цветов легенды, иначе цвета на графике не совпадут с подписями каналов. Гистограмма, смещённая влево, означает тёмное изображение, вправо — светлое; узкий пик говорит о низком контрасте. Используйте это для диагностики экспозиции и баланса белого.

opencv
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), эквализируйте яркость и конвертируйте обратно.

opencv
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 — значение по умолчанию; меньшие тайлы дают больше локальной адаптации. Основной выбор для медицинской визуализации и улучшения документов.

opencv
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, потому что учит фактическое цветовое распределение цели.

opencv
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)
13

Детекция признаков

Детектор углов Харриса

Харрис обнаруживает углы, проверяя, вызывает ли сдвиг небольшого окна в любом направлении сильное изменение интенсивности: углы меняются во всех направлениях, края — в одном, плоские области — ни в одном. Выход — карта отклика углов; порог задавайте относительно максимума (например, 0.01 * max). blockSize — окрестность для вычисления структурного тензора.

opencv
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 обеспечивает пространственное разделение найденных углов. Это стандартный вход для трекера оптического потока Лукаса-Канаде.

opencv
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 рисует масштаб и ориентацию каждой ключевой точки.

opencv
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, но отличен за свою цену.

opencv
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). Ниже порог — больше (и шумнее) углов; подавление немаксимумов убирает дубликаты в локальных максимумах.

opencv
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 находит области, стабильные в диапазоне порогов интенсивности, — идеально для детекции текста (буквы похожи на пятна), номерных знаков и текста на сцене. Он хорошо справляется с неравномерным освещением, потому что каждая область обнаруживается при своём пороге. Фильтруйте результаты по соотношению сторон и размеру, чтобы убрать очевидно не текстовые области.

opencv
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)
14

Сопоставление признаков

Полный перебор (brute force)

Brute-force сопоставление перебирает каждую пару дескрипторов — точно, но O(N*M). Для бинарных дескрипторов ORB используйте NORM_HAMMING; для float-дескрипторов SIFT/SURF — NORM_L2. crossCheck=True оставляет только взаимно лучшие совпадения (лучшее у A — B, и наоборот), что убирает много ложных срабатываний. У каждого совпадения есть .distance — меньше лучше.

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

opencv
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). Интуиция: если оба кандидата одинаково близки, совпадение неоднозначно и, вероятно, неверно. Один этот тест убирает подавляющее большинство ложных срабатываний.

opencv
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 хороших совпадения. Используйте это, чтобы найти известный объект на сцене или совместить перекрывающиеся фотографии.

opencv
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-объектов (где доминирует перспектива). Ломается на бестекстурных, симметричных или сильно перекрытых объектах — для них используйте детекторы на глубоком обучении.

opencv
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)
15

Детекция лиц

Каскадный классификатор Хаара

Каскады Хаара — классический детектор Виолы-Джонса: быстры на CPU и хороши для фронтальных лиц, но менее точны, чем современные детекторы на глубоком обучении (MTCNN, SSD, RetinaFace). scaleFactor (>1) управляет многомасштабным поиском: 1.1 = шаг 10%; меньше — медленнее, но тщательнее. minNeighbors фильтрует перекрывающиеся детекции; увеличивайте его, чтобы уменьшить ложные срабатывания.

opencv
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 ДО вызова каскада.

opencv
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 и сглаживайте фильтром Калмана: одни каскады не имеют временной непрерывности.

opencv
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) обрабатывают все позы одной моделью.

opencv
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).

opencv
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)
16

Детекция объектов

Дескриптор HOG

HOG (гистограмма ориентированных градиентов) описывает локальную форму через гистограммы направлений краёв; в сочетании с линейным SVM это классический детектор объектов. Предобученный детектор людей работает для пешеходов в полный рост в вертикальных позах. winStride и scale обменивают скорость на полноту. Современные глубокие детекторы (YOLO, SSD) гораздо точнее, но HOG работает на CPU без файла модели.

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

opencv
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]. Для нескольких совпадений порогуйте карту отклика и применяйте подавление немаксимумов, чтобы избежать перекрывающихся детекций.

opencv
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), а не сопоставление шаблонов.

opencv
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 с более быстрым бэкендом.

opencv
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
17

Сегментация изображений

Кластеризация K-Means

K-means кластеризует пиксели по цвету — простой способ постеризовать или сегментировать изображение на K доминирующих цветов. Передавайте пиксели float32 формы (N, 3) (или (N, 5), если добавите координаты xy для пространственной кластеризации). Большее K даёт более тонкое разделение цветов. Для пространственной связности добавьте к каждому пикселю координаты (x, y); для чистой квантизации цвета используйте только BGR.

opencv
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, вручную разметив пиксели (точно передний план / точно фон). Хорошо работает для одного заметного объекта на относительно простом фоне.

opencv
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=граница. Это классический конвейер «разделения касающихся объектов».

opencv
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 пиксель с каждой стороны). Полезно для выращивания областей, простой замены фона и интерактивного выделения.

opencv
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 для более строгой. Используйте для подсчёта частиц и анализа пятен.

opencv
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 (цветовой радиус) — допуском по цвету. Большие значения дают более крупные и гладкие области.

opencv
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)
18

Калибровка камеры

Калибровка по шахматной доске

Калибровка камеры находит внутреннюю матрицу (фокусное расстояние, главная точка) и коэффициенты искажений объектива по изображениям известного шаблона (шахматная доска стандартна, потому что углы легко детектируются). Нужно ~10–20 изображений с разных углов. cornerSubPix уточняет углы до субпиксельной точности — необходимо для хорошей калибровки. Размер шаблона для findChessboardCorners — внутренние углы (квадраты-1).

opencv
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 обрезает до допустимой области.

opencv
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, длина в метрах.

opencv
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 трекинга.

opencv
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 обычно указывает на плохой набор изображений, неверный размер шаблона или смаз. Ошибка по каждому изображению помогает найти и отбросить неудачные кадры калибровки.

opencv
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
19

Глубина и стерео

Карта диспаратности

StereoBM вычисляет карту диспаратности (пиксельное смещение между левым и правым) для откалиброванной стереопары: близкие объекты имеют большую диспаратность. numDisparities должен быть кратен 16; blockSize — нечётным. Выход — int16, масштабированный на 16 (делите на 16.0 для диспаратности в пикселях). StereoSGBM (полуглобальное блочное сопоставление) медленнее, но гораздо точнее.

opencv
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* фильтруют мелкие шумные области диспаратности.

opencv
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 каждого кадра. После ректификации вычисление диспаратности — одномерный поиск вдоль строк.

opencv
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. База (расстояние между камерами) и фокусное расстояние должны быть в согласованных единицах (обычно фокус в пикселях, база в метрах даёт глубину в метрах). Диспаратность шумна для далёких объектов (малая диспаратность — большая ошибка глубины), поэтому стереокамерам нужна широкая база для дальнего диапазона.

opencv
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 — гораздо медленнее, но даёт полное поле движения.

opencv
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()
20

Утилиты и советы

Измерение производительности

TickMeter — самый чистый способ бенчмарка вызовов OpenCV: getTimeMilli возвращает миллисекунды по настенным часам. getTickCount/getTickFrequency дают точный по тактам тайминг. Всегда усредняйте по многим итерациям, чтобы амортизировать дрожание, и отключайте cv2.imshow при бенчмарке (рендеринг GUI доминирует). setNumThreads управляет нижележащим параллельным бэкендом (TBB/OpenMP).

opencv
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 фиксирована.

opencv
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).

opencv
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].

opencv
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 попадает в каждую хотя бы раз.

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

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.