Primeiros Passos
Ler, Mostrar e Salvar Imagens
OpenCV lê imagens em ordem BGR (não RGB) — pegadinha comum ao interoperar com matplotlib ou PIL. cv2.waitKey(0) bloqueia até uma tecla ser pressionada; sempre chame destroyAllWindows() para fechar janelas. A qualidade do JPEG vai de 0-100.
import cv2
import numpy as np
# read an image (BGR format by default)
img = cv2.imread("photo.jpg")
print(img.shape) # (height, width, channels)
# read as grayscale
gray = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# read with alpha channel
rgba = cv2.imread("logo.png", cv2.IMREAD_UNCHANGED)
# display
cv2.imshow("window", img)
cv2.waitKey(0)
cv2.destroyAllWindows()
# save
cv2.imwrite("output.jpg", img, [cv2.IMWRITE_JPEG_QUALITY, 90])Instalação e Import
opencv-python traz só os módulos principais; opencv-contrib-python adiciona módulos extras (frequentemente restritos por patentes) como SIFT/SURF e ArUco. Use a variante headless em servidores/Docker para evitar puxar dependências do X11. Apesar do nome cv2, o OpenCV 4.x ainda é importado como cv2.
# Install OpenCV (Python bindings)
pip install opencv-python # main modules only
pip install opencv-contrib-python # includes extra modules (SIFT, SURF, aruco...)
pip install opencv-python-headless # no GUI (servers / Docker)
# The universal alias is cv2
import cv2
print(cv2.__version__) # e.g. 4.9.0
# NumPy is required — images are ndarray
import numpy as npImagem como Array NumPy
Imagens OpenCV são arrays NumPy, então tudo que você sabe de NumPy se aplica. A convenção de coordenadas é img[y, x] (linha, coluna) — o oposto das coordenadas de imagem (x, y), fonte frequente de bugs. Imagens coloridas são (A, L, 3) em BGR; escala de cinza é (A, L).
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-299Acesso a Pixels e ROI
Acesso pixel a pixel via img[y, x] é lento e desencorajado em loops — sempre prefira slicing NumPy. Use .copy() ao atribuir uma ROI para que mudanças posteriores na fonte não vazem para dentro. Modificar img[:, :, canal] é a forma mais rápida de operar num único canal de cor.
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 channelTipos de Dados e Conversão
A maioria das funções OpenCV espera uint8 (0-255), mas algoritmos como SIFT, fluxo óptico e detecção de bordas frequentemente precisam de float32. Nunca faça cast direto com .astype() após subtração — overflow de uint8 transforma -1 em 255. Use cv2.absdiff ou converta para float primeiro. Sempre faça cast de volta para uint8 antes de cv2.imwrite / imshow.
import cv2
import numpy as np
img = cv2.imread("photo.jpg") # uint8, 0-255
print(img.dtype, img.min(), img.max()) # uint8 0 255
# convert to float32 (0.0-1.0 for many algorithms)
f = img.astype(np.float32) / 255.0
# convert back to uint8 for display/save
u = (f * 255).astype(np.uint8)
# clamp then cast (avoid overflow when subtracting)
diff = cv2.absdiff(img, img) # safe subtraction
print(diff.dtype) # uint8
# CV_32F / CV_64F / CV_8U constants (used in some functions)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print(gray.dtype) # uint8Captura de Vídeo
Abrir Webcam
VideoCapture(0) abre a webcam padrão; use 1, 2... para câmeras adicionais. Sempre chame cap.release() para liberar o dispositivo — esquecer pode deixar a câmera ocupada para outros apps. waitKey(1) espera ~1ms; o truque & 0xFF garante compatibilidade em sistemas de 64 bits em que waitKey retorna mais de 8 bits.
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()Ler Arquivo de Vídeo
CAP_PROP_FRAME_COUNT costuma ser aproximado e não confiável para alguns codecs — não conte com ele para buscas exatas. waitKey(int(1000/fps)) reproduz a uma velocidade aproximadamente correta; para tempo preciso, use um relógio real. Alguns vídeos comprimidos não abrem sem o backend certo (FFmpeg).
import cv2
cap = cv2.VideoCapture("movie.mp4")
# video properties
fps = cap.get(cv2.CAP_PROP_FPS)
width = cap.get(cv2.CAP_PROP_FRAME_WIDTH)
height = cap.get(cv2.CAP_PROP_FRAME_HEIGHT)
count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
print(f"{width}x{height} @ {fps} fps, {count} frames")
while cap.isOpened():
ret, frame = cap.read()
if not ret:
break
cv2.imshow("video", frame)
if cv2.waitKey(int(1000 / fps)) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Salvar / Gravar Vídeo
O código FourCC depende de plataforma e codec: 'mp4v' é amplamente portátil, 'XVID' produz .avi, 'avc1' dá H.264 (pode não estar disponível sem codecs proprietários). O tamanho de quadro passado ao VideoWriter PRECISA casar com os quadros que você grava, senão o arquivo corrompe. Sempre chame out.release() para descarregar e fechar o arquivo.
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()Configurações de Câmera
Propriedades de câmera dependem de hardware e driver — muitas webcams ignoram silenciosamente configurações não suportadas ou arredondam para o valor válido mais próximo, então sempre leia de volta o valor real. CAP_PROP_EXPOSURE usa log2 de segundos (-4 = 1/16 s). A exposição automática precisa ser desativada (definida como 1) antes que a exposição manual tenha efeito na maioria das câmeras.
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 differTaxa de Quadros e Tempo
cap.get(CAP_PROP_FPS) retorna o FPS configurado, não a taxa real de captura — meça com um relógio real. Uma média móvel de 30 quadros suaviza jitter. Os maiores assassinos de FPS são cv2.imshow (thread de GUI) e cv2.imwrite por quadro; para benchmarks, desative a exibição. Para tempo determinístico, acumule quadros numa thread e processe de uma fila.
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()Desenho
Linha e Retângulo
Todas as funções de desenho mutam a imagem no próprio local — passe uma cópia se quiser manter a original. As coordenadas são (x, y), o oposto da indexação [y, x] do NumPy. Cores são tuplas BGR. Use thickness=-1 para formas preenchidas e cv2.LINE_AA para linhas suaves (com anti-aliasing) em bordas diagonais.
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)Círculo e Elipse
O parâmetro axes da ellipse é (meiaLargura, meiaAltura) — a largura completa é 2 * axes[0]. angle rotaciona a elipse inteira; startAngle/endAngle desenham arcos parciais (0° = direita, anti-horário). Desenhar arcos parciais é a forma padrão de renderizar fatias de gráfico de pizza ou indicadores de direção de movimento.
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)Polígono e Polylines
polylines aceita uma lista de arrays de pontos, então você pode desenhar múltiplos polígonos numa única chamada. O array de pontos deve ser int32 e remodelado para (-1, 1, 2). Use fillPoly para formas preenchidas; para preenchimentos translúcidos, desenhe num overlay e misture com addWeighted. A flag isClosed liga o último ponto ao primeiro.
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)Texto
As fontes embutidas do OpenCV são fontes vetoriais Hershey — não suportam caracteres CJK/chineses. Para texto não latino, renderize com ImageFont do PIL (Pillow) e converta de volta, ou use cv2.freetype do opencv-contrib. getTextSize retorna ((largura, altura), linha_de_base) — útil para centralizar texto ou desenhar uma caixa de fundo atrás dele.
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)Seta e Marcador
O tipLength do arrowedLine é uma fração do comprimento da linha, então setas mais longas têm pontas proporcionalmente maiores — defina-o explicitamente se quiser tamanhos de ponta de seta consistentes. drawMarker é conveniente para destacar pontos-chave (ex.: features ou cantos detectados); MARKER_TILTED_CROSS dá um marcador em forma de X.
import cv2
import numpy as np
img = np.zeros((400, 400, 3), dtype=np.uint8)
# arrowedLine(img, pt1, pt2, color, thickness, tipLength)
cv2.arrowedLine(img, (50, 50), (350, 50), (0, 255, 0), 2, tipLength=0.05)
cv2.arrowedLine(img, (200, 200), (200, 380), (0, 0, 255), 3, tipLength=0.1)
# drawMarker (cross, tilted cross, circle, square, diamond)
cv2.drawMarker(img, (100, 300), (255, 0, 255),
markerType=cv2.MARKER_CROSS, markerSize=30, thickness=2)
cv2.drawMarker(img, (300, 300), (255, 255, 0),
markerType=cv2.MARKER_DIAMOND, markerSize=30, thickness=2)
cv2.imshow("img", img)
cv2.waitKey(0)Overlay e Anotação
A técnica de overlay (desenhar numa cópia e depois addWeighted) é a forma padrão de desenhar preenchimentos translúcidos — o OpenCV não tem alfa nativo para formas. Sempre desenhe o texto sólido DEPOIS da mistura, para que fique nítido; desenhar texto no overlay antes da mistura o deixa borrado. Esse padrão está em toda visualização de detecção/segmentação.
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)Aritmética de Imagens
Soma e Subtração
O cv2.add do OpenCV satura em 255 (250 + 10 = 255), enquanto o + do NumPy dá a volta (250 + 10 = 8, por overflow de uint8). Para imagens, sempre use cv2.add / cv2.subtract — o wrap cria artefatos visíveis de preto/branco. absdiff é o cavalo de batalha para subtração de fundo e detecção de movimento.
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)Mistura e AddWeighted
addWeighted exige que ambas as imagens tenham tamanho e dtype idênticos — redimensione primeiro. O termo gamma soma uma constante a cada pixel, útil para controle de brilho. O clássico fade/dissolver entre duas imagens é só addWeighted com o alfa varrendo de 0 a 1.
import cv2
import numpy as np
a = cv2.imread("a.jpg")
b = cv2.imread("b.jpg")
b = cv2.resize(b, (a.shape[1], a.shape[0]))
# dst = alpha * a + beta * b + gamma
blend = cv2.addWeighted(a, 0.7, b, 0.3, 0)
# brighten by adding a constant (gamma)
bright = cv2.addWeighted(a, 1.0, a, 0.0, 50)
# fade between two images over N steps
for i in range(11):
alpha = i / 10.0
frame = cv2.addWeighted(a, alpha, b, 1 - alpha, 0)
cv2.imshow("fade", frame)
cv2.waitKey(200)Operações Bit a Bit
Operações bit a bit são a forma padrão de aplicar uma máscara: cv2.bitwise_or(src, dst, mask=mascara) copia src para dst só onde a máscara é não zero. A máscara deve ser uma imagem de 8 bits de canal único, em que não zero significa 'manter'. Esta é a fundação da extração de ROI e da substituição de fundo.
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)Diferença de Imagem e Movimento
Diferença de quadros é o detector de movimento mais simples: binarize a diferença absoluta entre quadros consecutivos. Falha quando a câmera se move e ignora movimento lento — para sistemas reais use subtração de fundo (cv2.createBackgroundSubtractorMOG2) ou fluxo óptico. Abertura morfológica remove ruído; dilatação une blobs próximos.
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 e Mascaramento
bitwise_and com máscara é a forma idiomática de extrair regiões irregulares. A indexação booleana NumPy (img[mascara]) é mais flexível, mas retorna um array plano de pixels, não uma imagem com forma. Sempre faça .copy() das ROIs que planeja reutilizar — o slicing retorna uma view que aponta para a original.
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] = 0Saturação vs Enrolamento
A armadilha do overflow uint8: NumPy dá a volta (300 -> 44), OpenCV satura (300 -> 255). Para qualquer aritmética que possa exceder 0-255, use cv2.add/subtract ou promova para int16/float32 primeiro e recorte depois. Misturar operações cv2 e NumPy no mesmo pipeline é a fonte nº 1 de misteriosos artefatos de pixels escuros/claros.
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 -> 44Transformações Geométricas
Resize / Escala
INTER_AREA é melhor para redução (evita aliasing), INTER_CUBIC ou INTER_LINEAR para ampliação. INTER_NEAREST é a mais rápida, mas blocosa — usada para imagens de rótulo/máscara, em que você não pode introduzir novos valores de pixel. A tupla dsize é (largura, altura), o oposto de img.shape, que é (altura, largura).
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) # enlargingRotação
cv2.rotate é muito mais rápido que warpAffine para múltiplos de 90°. O ângulo do getRotationMatrix2D está em graus, positivo = anti-horário. Para rotacionar sem cortar, recalcule a bounding box (nova_l, nova_a) e desloque a matriz de rotação — senão os cantos de uma imagem grande rotacionada são cortados.
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))Transformação Afim
Uma transformação afim preserva paralelismo e razões de distâncias — definida por 3 correspondências de pontos (6 graus de liberdade). warpAffine usa mapeamento direto implicitamente via busca inversa, então M mapeia src->dst, mas a função o inverte internamente. Use borderMode=BORDER_REFLECT ou BORDER_CONSTANT para controlar como regiões fora dos limites são preenchidas.
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)Transformação de Perspectiva
Perspectiva (homografia) é definida por 4 pares de pontos não colineares — 8 GL. Esta é a transformação padrão de 'scanner de documentos': pegue os 4 cantos de um cartão/papel na foto e deforme para um retângulo. getPerspectiveTransform precisa de exatamente 4 pontos; para um ajuste superdeterminado use cv2.findHomography com RANSAC.
import cv2
import numpy as np
img = cv2.imread("card.jpg")
h, w = img.shape[:2]
# 4 point correspondences define a perspective (homography)
src = np.float32([[73, 110], [320, 78], [380, 350], [40, 320]])
dst = np.float32([[0, 0], [w, 0], [w, h], [0, h]])
M = cv2.getPerspectiveTransform(src, dst)
warped = cv2.warpPerspective(img, M, (w, h))
# invert the homography to map back
M_inv = cv2.getPerspectiveTransform(dst, src)
restored = cv2.warpPerspective(warped, M_inv, (w, h))Flip e Espelho
flip é uma operação barata em memória — muito mais rápida que warpAffine. Convenção de sinal do flipCode: positivo espelha horizontalmente, 0 verticalmente, negativo ambos. cv2.transpose troca os eixos e às vezes é usada como rotação rápida de 90° quando combinada com um flip.
import cv2
img = cv2.imread("photo.jpg")
# flip(img, flipCode)
# 0 -> vertical flip (around x-axis) (upside-down)
# 1 -> horizontal flip (around y-axis) (mirror)
# -1 -> both (180° rotation equivalent)
v = cv2.flip(img, 0)
h = cv2.flip(img, 1)
both = cv2.flip(img, -1)
# transpose (swap x and y axes) — like a 90° rotation + flip
t = cv2.transpose(img)Remap (Mapeamento Personalizado)
remap é a transformação geométrica mais geral — resize, rotação e até correção de distorção de lente/barril podem ser expressos como remap. Sempre construa os mapas com vetorização NumPy, não loops Python (a versão com loop acima é só ilustrativa — ~100x mais lenta). INTER_LINEAR é o padrão; para precisão subpixel nas bordas use INTER_CUBIC.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# build coordinate maps: map_x, map_y say where each output pixel comes from
map_x = np.zeros((h, w), dtype=np.float32)
map_y = np.zeros((h, w), dtype=np.float32)
for y in range(h):
for x in range(w):
# mirror the image
map_x[y, x] = w - 1 - x
map_y[y, x] = y
remapped = cv2.remap(img, map_x, map_y, cv2.INTER_LINEAR)
# vectorized version (much faster) — wave distortion
xs, ys = np.meshgrid(np.arange(w), np.arange(h))
map_x = xs.astype(np.float32) + 10 * np.sin(ys / 20.0)
map_y = ys.astype(np.float32) + 10 * np.cos(xs / 20.0)
wave = cv2.remap(img, map_x, map_y, cv2.INTER_LINEAR,
borderMode=cv2.BORDER_REFLECT)Filtragem de Imagens
Desfoque Médio (Box Filter)
O desfoque médio é o filtro passa-baixa mais simples — substitui cada pixel pela média da sua vizinhança. Os kernels devem ser ímpares e positivos. Kernels maiores desfocam mais, mas também destroem detalhes mais rápido. Use quando você quer especificamente ponderação uniforme; para imagens naturais, o desfoque gaussiano quase sempre é escolha melhor.
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)Desfoque Gaussiano
O desfoque gaussiano é o kernel de suavização padrão — pondera os vizinhos por uma gaussiana, preservando bordas melhor que o box filter. Se você passar ksize=(0,0) e sigmaX, o OpenCV computa o tamanho do kernel automaticamente. O desfoque gaussiano é passo prévio obrigatório antes de Canny, redução de resolução e Laplaciano, para suprimir a amplificação de ruído.
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)Desfoque de Mediana
O desfoque de mediana é o filtro padrão para ruído sal-e-pimenta (impulso) — substitui cada pixel pela mediana da sua vizinhança, então outliers isolados são removidos em vez de espalhados. Diferente do gaussiano, preserva bem as bordas. O tamanho do kernel deve ser ímpar. É mais lento que gaussiano/box, pois envolve ordenação.
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)Filtro Bilateral
A filtragem bilateral suaviza regiões planas mantendo bordas nítidas — é um filtro não linear que preserva bordas, ponderando vizinhos por proximidade espacial E similaridade de cor. É muito mais lenta que a gaussiana (frequentemente 10x). A aplicação repetida é o clássico passo de pré-processamento do 'cartoonificador'; valores grandes de sigmaColor misturam através de mais cores.
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)Nitidez (Kernel)
Kernels de nitidez enfatizam altas frequências — mas também amplificam ruído, então aplique-os após a remoção de ruído. O kernel clássico de nitidez 3x3 soma 1 (preserva o brilho); soma > 1 clareia. A técnica de unsharp mask (subtrair uma cópia desfocada) é mais controlável e é o que a maioria dos editores de foto realmente usa.
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)Kernel Personalizado (filter2D)
filter2D aplica um kernel de correlação arbitrário — ddepth=-1 mantém a profundidade da fonte. Kernels podem ser float para coeficientes negativos; se o resultado ficar negativo, troque ddepth=cv2.CV_16S ou CV_32F e depois convertScaleAbs de volta. Kernels separáveis (produto externo de kernels 1D) são muito mais rápidos via sepFilter2D.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# emboss kernel
emboss = np.array([[-2, -1, 0],
[-1, 1, 1],
[ 0, 1, 2]], dtype=np.float32)
out = cv2.filter2D(img, -1, emboss)
# edge enhance (Laplacian-like)
edge = np.array([[ 0, 1, 0],
[ 1, -4, 1],
[ 0, 1, 0]], dtype=np.float32)
edges = cv2.filter2D(img, -1, edge)
# box blur done manually
box = np.ones((5, 5), dtype=np.float32) / 25.0
blurred = cv2.filter2D(img, -1, box)
# separable filter (Gaussian) — faster than 2D
kx = cv2.getGaussianKernel(5, 1.0) # 5x1
ky = cv2.getGaussianKernel(5, 1.0) # 5x1
g2d = kx @ ky.T # 5x5
out2 = cv2.filter2D(img, -1, g2d)Operações Morfológicas
Erosão e Dilatação
A erosão encolhe regiões de primeiro plano (brancas) e remove pontinhos de ruído; a dilatação as cresce e preenche buracos pequenos. A forma do kernel importa: RECT para uso geral, ELLIPSE para features mais redondas, CROSS para afinar/conectar ao longo dos eixos. iterations=N repete a operação N vezes, equivalente a usar um kernel maior.
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))Abertura e Fechamento
A abertura (erodir→dilatar) remove pontinhos claros pequenos sem mudar o tamanho de objetos maiores. O fechamento (dilatar→erodir) preenche buracos escuros pequenos. São idempotentes — aplicar duas vezes é igual a aplicar uma. O padrão clássico de denoising é fechar-então-abrir (ou abrir-então-fechar) para tratar ambos os tipos de defeito.
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)Gradiente Morfológico
O gradiente morfológico (dilatação - erosão) produz um contorno grosso dos limites dos objetos — útil como detector de bordas rápido ou como máscara para segmentação. Diferente do Canny, dá bordas preenchidas e largas, então serve mais para destacar regiões do que para medir posições exatas de bordas.
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 e Black Hat
Top-hat extrai pequenas estruturas claras menores que o kernel (ex.: texto num documento escuro); black-hat extrai pequenas estruturas escuras. Juntos, são usados para extração de sombra/realce e como corretor rápido de iluminação desigual (o truque de dividir pelo fundo é comum em scanners de documentos).
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)Esqueletização
A esqueletização morfológica afina uma forma binária a um eixo medial de 1 pixel de largura — útil para OCR, análise de impressões digitais e vasos. O loop iterativo erodir-subtrair-abrir roda até a imagem ficar vazia. Para uso em produção, o medial_axis ou thinning do scikit-image é mais rápido e dá resultados mais limpos.
import cv2
import numpy as np
img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, img = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
# skeleton via iterative morphological opening
kernel = np.ones((3, 3), np.uint8)
skeleton = np.zeros_like(img)
while True:
eroded = cv2.erode(img, kernel)
opened = cv2.morphologyEx(eroded, cv2.MORPH_OPEN, kernel)
temp = cv2.subtract(eroded, opened)
skeleton = cv2.bitwise_or(skeleton, temp)
img = eroded
if cv2.countNonZero(img) == 0:
breakHit-or-Miss
Hit-or-miss é o casador de padrões morfológico — encontra configurações exatas de pixels de primeiro plano e fundo, útil para detectar formas específicas como cantos ou junções em T. O kernel usa 1 para primeiro plano obrigatório, -1 para fundo obrigatório, 0 para indiferente. É nicho, mas imbatível para localização exata de padrões.
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")Detecção de Bordas
Detector de Bordas Canny
Canny é o detector de bordas mais usado: suavização gaussiana → gradientes Sobel → supressão não máxima → histerese (dois limiares). Pixels acima do limiar alto são bordas; os entre o baixo e o alto são bordas só se conectados a uma borda forte. O truque de limiar automático (mediana × 0.7/1.3) funciona bem para imagens variadas.
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)Operador Sobel
Sobel computa a primeira derivada — use ddepth=cv2.CV_64F (ou CV_16S) para capturar gradientes negativos, senão o overflow de uint8 torna invisíveis as transições de escuro para claro. ksize=3 é padrão; ksize=5 dá bordas mais suaves, porém mais largas. A magnitude (sqrt(sx²+sy²)) é a base do Canny e de muitos detectores de features.
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)Laplaciano
O Laplaciano é a segunda derivada — muito sensível a ruído, então sempre desfoque primeiro. Detecta cruzamentos por zero (mudanças de sinal), dando bordas finas e precisas, mas sem direção. Mais usado na detecção de bordas de Marr-Hildreth e como entrada do canal 'L' na nitidez de imagens (unsharp mask). Use CV_64F, porque a segunda derivada balança muito para o negativo.
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)Filtro Scharr
Scharr é uma variante do Sobel projetada para janelas 3x3 — quando você precisar usar um kernel pequeno, dá direção de gradiente mais precisa que Sobel ksize=3. Para kernels maiores (5x5, 7x7), Sobel serve. cv2.Sobel com ksize=-1 equivale a Scharr. Scharr é preferido quando a direção do gradiente importa (HOG, orientação de bordas).
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)Pipeline de Detecção de Bordas
O pipeline cinza → denoise → Canny → dilatar → findContours cobre uma enorme fração das tarefas práticas de bordas. A dilatação antes da busca de contornos fecha bordas quebradas que, de outro modo, dividiriam um objeto em vários. Ajustar os limiares do Canny e o tamanho do kernel de denoise é onde vai a maior parte do esforço de engenharia.
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)Contornos
Encontrar Contornos
findContours muta a imagem fonte no OpenCV 3.x — passe uma cópia se precisar da binária depois. RETR_EXTERNAL retorna só os contornos mais externos (o mais rápido); RETR_TREE dá a hierarquia completa para formas aninhadas (buracos dentro de objetos). CHAIN_APPROX_SIMPLE descarta pontos redundantes ao longo de linhas retas, economizando memória.
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)Desenhar Contornos
drawContours(imagem, contornos, contourIdx, cor, espessura): contourIdx=-1 desenha tudo; um índice específico desenha um. Espessura=-1 preenche o contorno. Desenhar numa imagem em branco é a forma padrão de construir uma máscara de contorno para operações downstream, como cor média ou histograma mascarado.
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)Propriedades de Contornos
contourArea é em pixels e ignora buracos (use o contorno com a hierarquia RETR_CCOMP para área líquida). O dicionário de momentos dá o centróide (m10/m00, m01/m00) — proteja contra divisão por zero se m00 for 0 (contornos degenerados). Razão de aspecto e extensão são os descritores de forma mais simples para classificação de formas.
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}")Retângulos Delimitadores
boundingRect dá uma caixa alinhada aos eixos (rápida, simples); minAreaRect dá o menor retângulo rotacionado (útil para medir a orientação/tamanho real de um objeto). boxPoints converte o rect rotacionado em 4 pontos de canto que você pode passar ao drawContours. minEnclosingCircle é o menor círculo contendo o contorno.
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)Aproximação de Contornos
approxPolyDP simplifica um contorno para um polígono com menos vértices usando o algoritmo Douglas-Peucker. O epsilon (tipicamente 1-5% do perímetro) controla a tolerância: menor mantém mais detalhe. Contar vértices é o classificador clássico de formas feito à mão — triângulos=3, retângulos=4, círculos=muitos.
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)Casco Convexo e Defeitos
O casco convexo é a menor forma convexa que envolve o contorno — útil para medir a compacidade de objetos e para detecção de mãos/dedos via defeitos de convexidade. A profundidade de cada defeito mede quão 'para dentro' o contorno mergulha em relação ao casco; defeitos profundos na silhueta de uma mão tipicamente correspondem a vãos entre dedos.
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)Binarização (Thresholding)
Limiar Básico
THRESH_BINARY: acima->255, abaixo->0. THRESH_TRUNC: acima->limitado em thresh, abaixo->inalterado. THRESH_TOZERO: acima->inalterado, abaixo->0. O ret retornado iguala o limiar de entrada para binarização simples, mas fica significativo para Otsu/Triangle. Escolha o tipo conforme como quer tratar pixels fora da faixa.
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)Limiar Adaptativo
A binarização adaptativa computa um limiar diferente para cada pixel com base na vizinhança local — essencial para imagens com iluminação desigual (ex.: fotografias de documentos). blockSize deve ser ímpar (tipicamente 11-31) e maior que o tamanho da feature. C subtrai uma constante da média local; aumente-a para suprimir ruído de baixo contraste.
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)Algoritmo de Otsu
O algoritmo de Otsu acha o limiar global ótimo maximizando a variância entre as classes de primeiro plano e fundo — passe thresh=0 e adicione a flag THRESH_OTSU. Sempre desfoque primeiro; Otsu é sensível a ruído no histograma. O algoritmo Triangle funciona melhor em imagens com um único pico dominante (ex.: microscopia). O ret retornado é o limiar computado.
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}")Limiar de Cor (inRange)
inRange é a ferramenta padrão de segmentação por cor — converta para HSV primeiro, porque separa a cor (hue) do brilho, tornando os limiares robustos a mudanças de iluminação. O hue do vermelho dá a volta em 0/180, então você precisa de duas máscaras combinadas com OR. Sempre desfoca antes do inRange para reduzir pontinhos de ruído na máscara.
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)Pipeline de Binarização
O pipeline denoise → limiar → morfologia trata a maioria das tarefas de binarização. Escolha Otsu para iluminação uniforme, adaptativo para desigual. O fechamento-então-abertura morfológico remove tanto buracos internos quanto pontinhos externos. Sempre inspecione a máscara binária — os parâmetros de limiar quase sempre são específicos da imagem e precisam de ajuste por dataset.
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)Binarização para OCR
Para OCR, o gaussiano adaptativo quase sempre supera o Otsu global em documentos fotografados, por causa da iluminação desigual. Casar blockSize com a altura dos caracteres (regra prática: 1-2× a largura do traço × 4). A maioria dos engines de OCR (Tesseract) prefere texto preto em fundo branco — inverta se sua binária estiver ao contrário.
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)Espaços de Cor
BGR / RGB / Cinza
OpenCV lê imagens como BGR por padrão; a maioria das outras bibliotecas (matplotlib, PIL, scikit-image) usa RGB. Esquecer cvtColor é a causa mais comum de imagens 'com vermelho e azul trocados'. A conversão para escala de cinza usa pesos perceptuais (Y = 0.299R + 0.587G + 0.114B), não uma média simples.
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 para HSV
O HSV do OpenCV usa H em 0-179 (não 0-360) para caber num uint8 — fonte frequente de bugs de 2x ao portar código de outras bibliotecas. S e V vão de 0-255. HSV é o espaço preferido para segmentação por cor, porque o hue é aproximadamente invariante a mudanças de brilho — use para rastreamento de objetos por cor.
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 para LAB
CIELAB aproxima a percepção humana — mudanças numéricas iguais parecem aproximadamente igualmente diferentes, razão pela qual é usado em métricas de diferença de cor (ΔE). O canal L codifica só a luminosidade, então editar L é a forma mais limpa de clarear uma imagem sem deslocar cores. O LAB do OpenCV usa 0-255 para cada um dos canais, não o padrão 0-100 para L.
import cv2
bgr = cv2.imread("photo.jpg")
# BGR -> LAB (perceptually uniform color space)
lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
L, A, B = cv2.split(lab)
# L: lightness (0-255), A: green<->red, B: blue<->yellow
# useful for separating luminance from color
# LAB is great for color-difference metrics (delta-E)
# and for editing lightness without affecting color
import numpy as np
lab_bright = lab.copy()
lab_bright[:, :, 0] = np.clip(lab_bright[:, :, 0].astype(int) + 30, 0, 255)
bgr_bright = cv2.cvtColor(lab_bright, cv2.COLOR_LAB2BGR)Rastreamento de Cor (HSV)
O rastreamento de cor baseado em HSV é o rastreador de objetos mais simples — escolha a faixa de hue, binarize, ache o maior blob. Falha sob iluminação ruim (baixa saturação), com objetos de fundo de cor similar e em superfícies refletoras. Para rastreamento robusto, combine com camshift/meanshift (usa retroprojeção de histograma de hue) ou um filtro de Kalman para suavizar o movimento.
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 e Merge de Canais
split/merge são convenientes, mas mais lentos que indexação NumPy — img[:, :, 0] é o canal azul e modificá-lo é mais rápido que split. Sempre passe os canais ao merge na ordem correta para o espaço de cor alvo. O truque de 'zerar dois canais' é a forma clássica de visualizar a contribuição de um único canal de cor.
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])Outros Espaços de Cor
YCrCb separa luminância (Y) de croma (Cr, Cb) — a base da compressão JPEG e MPEG, que descarta detalhe de croma porque humanos são menos sensíveis à cor que ao brilho. HLS difere do HSV em que o branco está em L=1 independentemente da saturação, tornando HLS melhor para alguns efeitos de sombreamento. Escolha o espaço que torna sua operação invariante ao que você não se importa.
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)Histogramas
Calcular Histograma
calcHist recebe uma lista de imagens, uma lista de canais, uma máscara opcional (None = imagem inteira), a contagem de bins e a faixa de valores. Para histogramas multidimensionais (ex.: hue-saturação 2-D), passe dois canais e dois tamanhos de bin — usado na retroprojeção de histograma para rastreamento de cor. O histograma de cada canal é computado independentemente.
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])Plotar Histograma
Matplotlib é a forma mais fácil de visualizar histogramas — mas lembre de converter BGR para RGB para as cores da legenda, senão as cores do seu gráfico não casam com os rótulos dos canais. Um histograma inclinado à esquerda é uma imagem escura, à direita clara; um pico estreito significa baixo contraste. Use isto para diagnosticar problemas de exposição e balanço de branco.
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()Equalização de Histograma
A equalização de histograma estica as intensidades dos pixels para usar toda a faixa 0-255 — ótima para imagens de baixo contraste, mas pode estourar realces e amplificar ruído. NUNCA equalize os três canais BGR diretamente — isso desloca cores. Sempre converta para um espaço de luminância/crominância (YCrCb, LAB, HSV), equalize a luminância e converta de volta.
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 (Equalização Adaptativa)
CLAHE é a alternativa de qualidade de produção à equalização global — opera em ladrilhos pequenos, então funciona em imagens com iluminação desigual, e clipLimit limita a amplificação de contraste para não explodir o ruído. tileGridSize de 8x8 é o padrão; ladrilhos menores dão mais adaptação local. A escolha padrão em imagens médicas e aprimoramento de documentos.
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)Retroprojeção de Histograma
A retroprojeção de histograma responde 'onde os pixels se parecem com a distribuição de cores da minha ROI?'. Construa um histograma hue-saturação 2-D de uma amostra e depois retroprojete numa imagem alvo para obter um mapa de probabilidade. É a base do rastreamento meanShift/camShift — muito mais robusto que uma faixa HSV fixa, porque aprende a distribuição real de cores do alvo.
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)Detecção de Features
Detector de Cantos de Harris
Harris detecta cantos verificando se mover uma pequena janela em qualquer direção causa uma grande mudança de intensidade — cantos mudam em todas as direções, bordas em uma, regiões planas em nenhuma. A saída é um mapa de resposta de canto; binarize relativo ao máximo (ex.: 0.01 * max). blockSize é a vizinhança para o cálculo do tensor de estrutura.
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 melhora Harris usando min(autovalor1, autovalor2) como pontuação, o que dá cantos mais estáveis para rastreamento. maxCorners limita a contagem; qualityLevel é uma fração da resposta de canto mais forte (0.01 = 1% do melhor); minDistance impõe separação espacial entre cantos detectados. Esta é a entrada padrão para o rastreador de fluxo óptico Lucas-Kanade.
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 (Features Invariantes a Escala)
SIFT acha keypoints invariantes a escala e rotação e um descritor 128-D para cada — robusto a iluminação, ponto de vista e oclusão parcial. Foi patenteado por anos e ficou gratuito no OpenCV 4.4. Use SIFT para casamento de alta precisão onde a velocidade é secundária. DRAW_RICH_KEYPOINTS desenha a escala e a orientação de cada keypoint.
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 combina o detector de keypoints FAST com o descritor BRIEF — ambos livres de patentes e ~10x mais rápidos que SIFT, tornando ORB a escolha padrão para casamento em tempo real em mobile/embedded. Os descritores são binários (32 bytes vs 128 floats do SIFT), então o casamento usa distância de Hamming. Um pouco menos robusto que SIFT a escala/rotação, mas excelente pelo custo.
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)Detector FAST
FAST testa se um círculo de 16 pixels ao redor de um candidato tem N pixels contíguos uniformemente mais claros ou uniformemente mais escuros que o centro — extremamente rápido, porque curto-circuita. Retorna só keypoints, sem descritores (use BRIEF ou ORB para descritores). Limiar menor = mais cantos (e mais ruidosos); a supressão não máxima remove duplicatas nos máximos locais.
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 (Regiões Extremais Estáveis)
MSER acha regiões que permanecem estáveis numa faixa de limiares de intensidade — ideal para detecção de texto (onde letras são tipo blob), placas de carro e texto de cena. Trata bem iluminação desigual, porque cada região é detectada no seu próprio limiar. Filtre os resultados por razão de aspecto e tamanho para remover não-texto óbvio.
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)Casamento de Features
Casamento por Força Bruta
O casamento por força bruta tenta cada par de descritores — exato, mas O(N*M). Para os descritores binários do ORB use NORM_HAMMING; para descritores float de SIFT/SURF use NORM_L2. crossCheck=True mantém só os melhores matches mútuos (o melhor de A é B e vice-versa), o que remove muitos falsos positivos. Cada match tem um .distance — menor é melhor.
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)Casamento FLANN
FLANN (Fast Library for Approximate Nearest Neighbors) constrói uma KD-tree (para SIFT/SURF) ou LSH (para ORB) para achar matches aproximados — muito mais rápido que força bruta em grandes conjuntos de descritores, ao custo de falhas ocasionais. Os parâmetros trees e checks trocam precisão por velocidade. Use FLANN quando tiver milhares de features; força bruta serve para conjuntos pequenos.
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)Casamento KNN e Teste de Razão
O teste de razão de Lowe é o filtro padrão para casamento de features: mantenha um match só se o melhor for significativamente mais próximo que o segundo melhor (limiar típico 0.7-0.8). A intuição: se ambos os candidatos estão igualmente próximos, o match é ambíguo e provavelmente errado. Esse único teste remove a vasta maioria dos falsos positivos.
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)Homografia (RANSAC)
findHomography com RANSAC computa a transformação de perspectiva que mapeia src em dst ignorando outliers — a máscara de inliers diz quais matches concordam com o modelo. O limiar de reprojeção (5.0) está em pixels; menor = mais estrito. Você precisa de pelo menos 4 bons matches. Use isto para localizar um objeto conhecido numa cena ou alinhar fotos sobrepostas.
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")Localização de Objetos
Este é o pipeline clássico de localização de objetos: detecte features em ambas as imagens, case-as, ajuste uma homografia com RANSAC e depois projete a bounding box do objeto na cena. Funciona para objetos planos ou objetos 3D distantes (onde a perspectiva domina). Falha em objetos sem textura, simétricos ou altamente ocluídos — para esses use detectores de deep learning.
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)Detecção de Rostos
Classificador Haar Cascade
Haar cascades são o detector clássico Viola-Jones — rápido na CPU e bom para rostos frontais, mas menos preciso que detectores modernos de deep learning (MTCNN, SSD, RetinaFace). scaleFactor (>1) controla a busca multi-escala — 1.1 = passo de escala de 10%; menor = mais lento, porém mais completo. minNeighbors filtra detecções sobrepostas; aumente para reduzir falsos positivos.
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)Detectar Rostos em Imagem
Detectar olhos (ou sorriso) dentro da ROI do rosto é o truque de eficiência padrão: buscar olhos na imagem inteira dá muitos falsos positivos, mas dentro de uma ROI de rosto confirmada são raros. cv2.data.haarcascades aponta para o diretório de XMLs incluídos — outros cascades (olho, sorriso, corpo inteiro, placa) estão disponíveis. Recorte a ROI ANTES de chamar o cascade.
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)Detectar Rostos em Vídeo
Detecção de rostos em tempo real na webcam é viável na CPU graças à velocidade dos Haar cascades. O truque de desfocar a ROI (GaussianBlur só na região do rosto) é uma técnica simples de privacidade/anonimização. Para rastrear rostos entre quadros (evitar tremedeira), associe detecções por IoU e suavize com um filtro de Kalman — cascades sozinhos não têm continuidade temporal.
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()Rosto de Perfil / Lateral
Haar cascades são específicos de pose — o cascade frontal perde rostos de lado, então combine com o cascade de perfil. Como o cascade de perfil é treinado num lado, detecte o outro lado espelhando a imagem horizontalmente e espelhando de volta as coordenadas resultantes. Isso ainda perde visões 3/4; detectores modernos (DNN, MTCNN) tratam todas as poses num único modelo.
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)Detecção de Rostos com DNN
O módulo dnn do OpenCV pode rodar modelos pré-treinados Caffe/TensorFlow/ONNX — detectores de rosto baseados em SSD e ResNet são muito mais precisos que Haar cascades e tratam todas as poses num único modelo. blobFromImage faz subtração de média e escala numa tacada só. As detecções são normalizadas [0,1] — multiplique por (l, a, l, a) para obter caixas em pixels. Modelos: SSD (Caffe), YuNet (ONNX, via cv.FaceDetectorYN).
import cv2
import numpy as np
model = cv2.dnn.readNetFromCaffe(
"deploy.prototxt", "weights.caffemodel")
img = cv2.imread("people.jpg")
h, w = img.shape[:2]
# build a 300x300 blob (mean subtraction + scale)
blob = cv2.dnn.blobFromImage(img, 1.0, (300, 300), (104, 177, 123))
model.setInput(blob)
detections = model.forward() # shape (1, 1, N, 7)
for i in range(detections.shape[2]):
conf = detections[0, 0, i, 2]
if conf > 0.5:
box = detections[0, 0, i, 3:7] * np.array([w, h, w, h])
x1, y1, x2, y2 = box.astype(int)
cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
cv2.putText(img, f"{conf:.2f}", (x1, y1 - 5),
cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1)Detecção de Objetos
Descritor HOG
HOG (Histogram of Oriented Gradients) descreve a forma local por histogramas de direções de bordas — combinado com um SVM linear, é um detector de objetos clássico. O detector de pessoas pré-treinado funciona para pedestres de corpo inteiro em poses eretas. winStride e scale trocam velocidade por recall. Detectores profundos modernos (YOLO, SSD) são muito mais precisos, mas HOG roda na CPU sem arquivo de modelo.
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)Visualização de Features HOG
A janela HOG padrão é 64x128 pixels (o tamanho de pedestre do INRIA). Parâmetros: janela (64x128), bloco (16x16), passo de bloco (8x8), célula (8x8), bins (9). Cada descritor tem 3780-D. Para classificar objetos personalizados, extraia features HOG de muitas amostras positivas/negativas e treine um SVM linear (scikit-learn), depois defina o detector com setSVMDetector.
import cv2
img = cv2.imread("person.jpg", cv2.IMREAD_GRAYSCALE)
img = cv2.resize(img, (64, 128)) # standard HOG window
hog = cv2.HOGDescriptor((64, 128), (16, 16), (8, 8), (8, 8), 9)
descriptor = hog.compute(img)
print(descriptor.shape) # (3780, 1)
# 9 bins per cell, 7x15 cells, 4 cells per block -> 3780 features
# this is the input vector to a linear SVM classifierCasamento de Templates
O casamento de templates desliza o template pela imagem e computa uma pontuação de similaridade — funciona só para matches exatos (ou quase exatos), sem rotação nem mudança de escala. TM_CCOEFF_NORMED é a opção mais robusta; os resultados vão de [-1, 1]. Para múltiplos matches, binarize o mapa de resposta e aplique supressão não máxima para evitar detecções sobrepostas.
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)Casamento de Templates Multi-escala
O casamento de templates multi-escala varre por força bruta uma faixa de escalas — lento, mas funciona quando o tamanho do template na imagem é desconhecido. Ainda não trata rotação; para isso você precisaria varrer ângulos também (muito lento) ou usar casamento de features. Para detecção de objetos em produção, use um detector treinado (YOLO, SSD) em vez de casamento de templates.
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)Detecção de Objetos com DNN (YOLO)
O módulo dnn do OpenCV pode rodar pesos exportados YOLO/SSD/Faster-RCNN — útil quando você não pode instalar um framework de DL completo. O parsing da saída do YOLO é verboso: cada detecção tem centro, tamanho, objetividade e pontuações por classe. Sempre aplique NMSBoxes (supressão não máxima) para colapsar caixas sobrepostas numa só. Para tempo real use YOLOv4-tiny ou troque para ONNX + um backend mais rápido.
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 suppressionSegmentação de Imagens
Clustering K-Means
K-means agrupa pixels por cor — uma forma simples de posterizar ou segmentar uma imagem nas K cores dominantes. Passe pixels float32 como (N, 3) (ou (N, 5) se adicionar coordenadas xy para clustering espacial). Aumentar K dá separação de cores mais fina. Para coerência espacial, acrescente a cada pixel suas coordenadas (x, y); para pura quantização de cor, use só BGR.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# reshape to a list of pixels (N, 3) in float32
pixels = img.reshape(-1, 3).astype(np.float32)
# kmeans(data, K, criteria, attempts, flags)
K = 4
criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)
_, labels, centers = cv2.kmeans(pixels, K, None, criteria, 10,
cv2.KMEANS_RANDOM_CENTERS)
# rebuild the image with cluster centers
centers = np.uint8(centers)
seg = centers[labels.flatten()].reshape((h, w, 3))GrabCut
GrabCut é um extrator de primeiro plano interativo — você dá um retângulo delimitador e ele modela iterativamente primeiro plano/fundo com Misturas Gaussianas. Para resultados mais finos, refine com GC_INIT_WITH_MASK depois de rotular pixels manualmente (primeiro plano certo / fundo certo). Funciona bem para um único objeto saliente contra um fundo relativamente simples.
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 trata a imagem como um mapa topográfico (intensidade = elevação) e 'inunda' bacias a partir de marcadores de semente — sem boas sementes produz severa sobre-segmentação. O truque da transformada de distância gera sementes de primeiro plano certo para objetos que se tocam (ex.: moedas sobrepostas). Marcadores: 0=desconhecido, 1=fundo, 2..N=objetos, -1=fronteira. É o pipeline clássico de 'separar objetos que se tocam'.
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 redFlood Fill
floodFill é a ferramenta varinha mágica — parta de um pixel semente e preencha cada um dos pixels conectados cuja cor esteja dentro de loDiff/upDiff da semente (FIXED_RANGE) ou do pixel anterior. A máscara deve ser 2 pixels maior que a imagem (uma borda de 1 pixel de cada lado). Útil para crescimento de região, substituição simples de fundo e seleção interativa.
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 1Componentes Conectados
connectedComponents rotula cada região branca com um inteiro único — mais rápido que findContours quando você só precisa de contagem, área e centróides. connectedComponentsWithStats também retorna bounding boxes e áreas. O rótulo 0 é sempre o fundo. A conectividade padrão é 8 (diagonais incluídas); passe connectivity=4 para mais estrita. Use para contagem de partículas e análise de blobs.
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 é uma segmentação não paramétrica que 'achata' regiões de cor similar preservando bordas — frequentemente usada como passo de pré-processamento antes de segmentação baseada em contornos. sp (raio espacial) controla quão longe o algoritmo olha espacialmente; sr (raio de cor) controla a tolerância de cor. Valores maiores produzem regiões maiores e mais suaves.
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)Calibração de Câmera
Calibração com Tabuleiro de Xadrez
A calibração de câmera acha a matriz intrínseca (distância focal, ponto principal) e os coeficientes de distorção da lente a partir de imagens de um padrão conhecido (tabuleiro de xadrez é padrão, porque os cantos são fáceis de detectar). Você precisa de ~10-20 imagens de ângulos variados. cornerSubPix refina cantos para precisão subpixel — essencial para uma boa calibração. O tamanho de padrão passado ao findChessboardCorners é de cantos internos (quadrados-1).
import cv2
import numpy as np
import glob
# prepare object points (0,0,0), (1,0,0), ..., for a 7x6 board
objp = np.zeros((6 * 7, 3), np.float32)
objp[:, :2] = np.mgrid[0:7, 0:6].T.reshape(-1, 2)
objpoints = [] # 3-D real-world points
imgpoints = [] # 2-D image points
for fname in glob.glob("calib/*.jpg"):
img = cv2.imread(fname)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# findChessboardCorners returns corners (or None)
ret, corners = cv2.findChessboardCorners(gray, (7, 6), None)
if ret:
# refine to sub-pixel accuracy
corners2 = cv2.cornerSubPix(gray, corners, (11, 11), (-1, -1),
(cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001))
objpoints.append(objp)
imgpoints.append(corners2)
# calibrate
ret, mtx, dist, rvecs, tvecs = cv2.calibrateCamera(
objpoints, imgpoints, gray.shape[::-1], None, None)
print("camera matrix:\n", mtx)Corrigir Distorção da Imagem
undistort remove a distorção radial e tangencial da lente usando os parâmetros de calibração. Para vídeo, pré-compute os mapas uma vez com initUndistortRectifyMap e aplique remap a cada quadro — muito mais rápido que chamar undistort repetidamente. getOptimalNewCameraMatrix com alpha=1 mantém cada um dos pixels (com bordas pretas); alpha=0 recorta para a região válida.
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]Estimativa de Pose (ArUco)
Marcadores ArUco são marcadores fiduciais quadrados (como QR codes) usados para estimativa de pose — dado o tamanho físico do marcador e a calibração da câmera, você obtém sua rotação 3-D (rvec) e translação (tvec) relativas à câmera. Disponível no opencv-contrib. drawFrameAxes desenha os eixos locais X/Y/Z do marcador — vermelho=X, verde=Y, azul=Z, comprimento em metros.
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)Pose Fiducial (SolvePnP)
solvePnP (Perspective-n-Point) recupera a pose da câmera a partir de N correspondências 3-D-para-2-D — precisa de pelo menos 4 pontos. Use SOLVEPNP_ITERATIVE (padrão) para precisão ou SOLVEPNP_IPPE para alvos planos. O rvec é um vetor de rotação (eixo × ângulo); use Rodrigues para converter numa matriz 3x3. É a fundação da AR baseada em marcadores e do rastreamento de 6 GL.
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)Erro de Reprojeção
O erro de reprojeção é o padrão-ouro da qualidade de calibração — mede quão longe os pontos 3-D projetados caem dos pontos 2-D detectados. Uma boa calibração fica abaixo de 0.5 px de média; acima de 1 px geralmente indica um conjunto ruim de imagens, tamanho de padrão errado ou motion blur. O erro por imagem ajuda a achar e descartar imagens ruins de calibração.
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 cornerProfundidade e Estéreo
Mapa de Disparidade Estéreo
StereoBM computa um mapa de disparidade (offset de pixel entre esquerda/direita) para um par estéreo retificado — objetos mais próximos têm disparidade maior. numDisparities deve ser múltiplo de 16; blockSize deve ser ímpar. A saída é int16 escalada por 16 (divida por 16.0 para disparidade em pixels). StereoSGBM (casamento de blocos semiglobal) é mais lento, mas muito mais preciso.
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 impõe suavidade entre linhas de varredura (casamento semiglobal) — muito mais preciso que StereoBM ao custo de ~5x de runtime. P1/P2 penalizam mudanças de disparidade de 1 e >1, respectivamente; regra prática é P1=8*C*blockSize² e P2=32*C*blockSize², em que C é a contagem de canais. Os parâmetros speckle* filtram regiões pequenas e ruidosas de disparidade.
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)Calibração e Retificação Estéreo
O casamento estéreo exige que as imagens estejam retificadas — linhas epipolares alinhadas horizontalmente, para que pontos correspondentes compartilhem uma linha. O pipeline é: calibrar cada câmera, calibrar estéreo para achar R e T entre elas, stereoRectify para computar as transformações de retificação, e depois remap de cada quadro uma vez. Após a retificação, o cálculo da disparidade é uma busca 1-D ao longo das linhas.
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)Profundidade a partir da Disparidade
A profundidade é inversamente proporcional à disparidade: profundidade = focal × base / disparidade. A base (separação das câmeras) e a distância focal devem estar em unidades consistentes (tipicamente pixels para focal, metros para base dá profundidade em metros). A disparidade é ruidosa para objetos distantes (disparidade pequena, grande erro de profundidade) — por isso câmeras estéreo precisam de base larga para alcance distante.
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)Fluxo Óptico (Lucas-Kanade)
Lucas-Kanade computa fluxo óptico esparso — rastreia um conjunto de keypoints entre quadros assumindo movimento local pequeno. Rápido e preciso para movimento moderado; falha em movimento grande ou rápido (use uma pirâmide, o que calcOpticalFlowPyrLK já faz). status==1 significa que o ponto foi rastreado com sucesso. Para fluxo denso por pixel use calcOpticalFlowFarneback — muito mais lento, mas produz um campo de movimento completo.
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()Utilitários e Dicas
Medição de Desempenho
TickMeter é a forma mais limpa de medir chamadas OpenCV — getTimeMilli retorna milissegundos de relógio. getTickCount/getTickFrequency dão tempo com precisão de ciclo. Sempre faça média de muitas iterações para amortizar jitter, e desative cv2.imshow ao medir (a renderização da GUI domina). setNumThreads controla o backend paralelo subjacente (TBB/OpenMP).
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# TickMeter: high-precision timer
tm = cv2.TickMeter()
tm.start()
for _ in range(100):
blurred = cv2.GaussianBlur(img, (5, 5), 0)
tm.stop()
print(f"avg: {tm.getTimeMilli() / 100:.3f} ms")
# getTickCount / getTickFrequency
t0 = cv2.getTickCount()
edges = cv2.Canny(img, 50, 150)
t1 = cv2.getTickCount()
print(f"Canny: {(t1 - t0) / cv2.getTickFrequency() * 1000:.2f} ms")
# set USE_AVX / thread count
cv2.setNumThreads(4)
print(cv2.getNumThreads())Eventos de Mouse
setMouseCallback registra um handler para eventos de mouse numa janela nomeada — útil para seleção interativa de ROI, ferramentas de anotação e apps simples de pintura. Eventos comuns: LBUTTONDOWN, LBUTTONUP, MOUSEMOVE, RBUTTONDOWN. O handler deve ser uma função de topo (ou global); globais são a forma padrão de compartilhar estado, porque a assinatura do callback é fixa.
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()Trackbar
Trackbars permitem ajustar parâmetros interativamente sem reiniciar o script — inestimável para achar bons limiares, tamanhos de kernel e faixas HSV. O callback é chamado a cada mudança (uma no-op serve, se você sondar getTrackbarPos no loop principal). Trackbars devem ser criadas numa janela nomeada e lidas com getTrackbarPos(janela, nome).
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()Seletor de ROI
selectROI abre uma janela interativa em que o usuário arrasta um retângulo e pressiona Enter/Espaço — muito mais fácil que escrever seu próprio callback de mouse. Pressione 'c' para cancelar (retorna só zeros). selectROIs permite escolher múltiplos retângulos um após o outro. A tupla retornada é (x, y, l, a); recorte com img[y:y+a, x:x+l].
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()Armadilhas Comuns
Estas cinco armadilhas causam a maioria dos bugs de OpenCV: confusão BGR/RGB (vermelho e azul trocados), overflow uint8 (artefatos escuros/claros), ordem de coordenadas (ROIs deslocadas de um), None por arquivo ausente (operações seguintes caem com erros crípticos) e esquecer waitKey (janelas não atualizam). Introduza-as cedo — cada desenvolvedor OpenCV esbarra em cada uma pelo menos uma vez.
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 blankSnippets de OpenCV relacionados
Copy-paste ready code for common tasks.
Read and Write Images
Load, display, and save images in various formats.
Resize and Crop
Resize with interpolation and crop regions of interest.
Color Conversion
Convert between BGR, RGB, HSV, and grayscale.
Blur and Filter
Smooth and sharpen images with kernels.
Edge Detection
Detect edges with Canny, Sobel, and Laplacian.
Contours
Find, draw, and measure contours.
Face Detection
Detect faces with a Haar cascade classifier.
Threshold
Apply binary, adaptive, and Otsu thresholding.
Was this helpful?